nodmix 2026.5.25

package/docs/plugins/codex-native-plugins.md

@@ -0,0 +1,276 @@
+---
+summary: "Configure migrated native Codex plugins for Codex-mode Nodmix agents"
+title: "Native Codex plugins"
+read_when:
+  - You want Codex-mode Nodmix agents to use native Codex plugins
+  - You are migrating source-installed openai-curated Codex plugins
+  - You are troubleshooting codexPlugins, app inventory, destructive actions, or plugin app diagnostics
+---
+
+Native Codex plugin support lets a Codex-mode Nodmix agent use Codex
+app-server's own app and plugin capabilities inside the same Codex thread that
+handles the Nodmix turn.
+
+Nodmix does not translate Codex plugins into synthetic `codex_plugin_*`
+Nodmix dynamic tools. Plugin calls stay in the native Codex transcript, and
+Codex app-server owns the app-backed MCP execution.
+
+Use this page after the base [Codex harness](/plugins/codex-harness) is working.
+
+## Requirements
+
+- The selected Nodmix agent runtime must be the native Codex harness.
+- `plugins.entries.codex.enabled` must be true.
+- `plugins.entries.codex.config.codexPlugins.enabled` must be true.
+- V1 supports only `openai-curated` plugins that migration observed as
+  source-installed in the source Codex home.
+- The target Codex app-server must be able to see the expected marketplace,
+  plugin, and app inventory.
+
+`codexPlugins` has no effect on PI runs, normal OpenAI provider runs, ACP
+conversation bindings, or other harnesses because those paths do not create
+Codex app-server threads with native `apps` config.
+
+## Quickstart
+
+Preview migration from the source Codex home:
+
+```bash
+nodmix migrate codex --dry-run
+```
+
+Use strict source app verification when you want migration to check source app
+accessibility before planning native plugin activation:
+
+```bash
+nodmix migrate codex --dry-run --verify-plugin-apps
+```
+
+Apply the migration when the plan looks right:
+
+```bash
+nodmix migrate apply codex --yes
+```
+
+Migration writes explicit `codexPlugins` entries for eligible plugins and calls
+Codex app-server `plugin/install` for selected plugins. A typical migrated
+config looks like this:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          codexPlugins: {
+            enabled: true,
+            allow_destructive_actions: true,
+            plugins: {
+              "google-calendar": {
+                enabled: true,
+                marketplaceName: "openai-curated",
+                pluginName: "google-calendar",
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+After changing `codexPlugins`, new Codex conversations pick up the updated app
+set automatically. Use `/new` or `/reset` to refresh the current conversation.
+A gateway restart is not required for plugin enable or disable changes.
+
+## Manage plugins from chat
+
+Use `/codex plugins` when you want to inspect or change configured native Codex
+plugins from the same chat where you operate the Codex harness:
+
+```text
+/codex plugins
+/codex plugins list
+/codex plugins disable google-calendar
+/codex plugins enable google-calendar
+```
+
+`/codex plugins` is an alias for `/codex plugins list`. The list output shows
+the configured plugin keys, on/off state, Codex plugin name, and marketplace
+from `plugins.entries.codex.config.codexPlugins.plugins`.
+
+`enable` and `disable` write only to Nodmix config at
+`~/.nodmix/nodmix.json`; they do not edit `~/.codex/config.toml` or install
+new Codex plugins. Only the owner or a gateway client with the
+`operator.admin` scope can change plugin state.
+
+Enabling a configured plugin also turns on the global
+`codexPlugins.enabled` switch. If the plugin was written disabled because
+migration returned `auth_required`, reauthorize the app in Codex before enabling
+it in Nodmix.
+
+## How native plugin setup works
+
+The integration has three separate states:
+
+- Installed: Codex has the local plugin bundle in the target app-server runtime.
+- Enabled: Nodmix config is willing to make the plugin available to Codex
+  harness turns.
+- Accessible: Codex app-server confirms the plugin's app entries are available
+  for the active account and can be mapped to the migrated plugin identity.
+
+Migration is the durable install/eligibility step. During planning, Nodmix
+reads source Codex `plugin/read` details and checks that the source Codex
+app-server account response is a ChatGPT subscription account. Non-ChatGPT or
+missing account responses skip app-backed plugins with
+`codex_subscription_required`. By default, migration does not call source
+`app/list`; app-backed source plugins that pass the account gate are planned
+without source app accessibility verification, and account lookup transport
+failures skip with `codex_account_unavailable`. With `--verify-plugin-apps`,
+migration takes a fresh source `app/list` snapshot and requires every owned app
+to be present, enabled, and accessible before planning native activation. In
+that mode, account lookup transport failures fall through to the source
+app-inventory gate. Runtime app inventory is the target-session accessibility
+check after migration. Codex harness session setup then computes a restrictive
+thread app config for the enabled and accessible plugin apps.
+
+Thread app config is computed when Nodmix establishes a Codex harness session
+or replaces a stale Codex thread binding. It is not recomputed on every turn, so
+`/codex plugins enable` and `/codex plugins disable` affect new Codex
+conversations. Use `/new` or `/reset` when the current conversation should pick
+up the updated app set.
+
+## V1 support boundary
+
+V1 is intentionally narrow:
+
+- Only `openai-curated` plugins that were already installed in the source Codex
+  app-server inventory are migration-eligible.
+- App-backed source plugins must pass the migration-time subscription gate.
+  `--verify-plugin-apps` adds the source app-inventory gate. Subscription-gated
+  accounts plus, in verification mode, inaccessible, disabled, missing source
+  apps or source app-inventory refresh failures are reported as skipped manual
+  items instead of enabled config entries. Unreadable plugin details are skipped
+  before the source app-inventory gate.
+- Migration writes explicit plugin identities with `marketplaceName` and
+  `pluginName`; it does not write local `marketplacePath` cache paths.
+- `codexPlugins.enabled` is the global enablement switch.
+- There is no `plugins["*"]` wildcard and no config key that grants arbitrary
+  install authority.
+- Unsupported marketplaces, cached plugin bundles, hooks, and Codex config files
+  are preserved in the migration report for manual review.
+
+## App inventory and ownership
+
+Nodmix reads Codex app inventory through app-server `app/list`, caches it for
+one hour, and refreshes stale or missing entries asynchronously. The cache is
+in memory only; restarting the CLI or gateway drops it, and Nodmix rebuilds it
+from the next `app/list` read.
+
+Migration and runtime use separate cache keys:
+
+- Source migration verification uses the source Codex home and source app-server
+  start options. This runs only when `--verify-plugin-apps` is set, and it
+  forces a fresh source `app/list` traversal for that planning run.
+- Target runtime setup uses the target agent's Codex app-server identity when it
+  builds the Codex thread app config. Plugin activation invalidates that target
+  cache key and then force-refreshes it after `plugin/install`.
+
+A plugin app is exposed only when Nodmix can map it back to the migrated
+plugin through stable ownership:
+
+- exact app id from plugin detail
+- known MCP server name
+- unique stable metadata
+
+Display-name-only or ambiguous ownership is excluded until the next inventory
+refresh proves ownership.
+
+## Thread app config
+
+Nodmix injects a restrictive `config.apps` patch for the Codex thread:
+`_default` is disabled and only apps owned by enabled migrated plugins are
+enabled.
+
+Nodmix sets app-level `destructive_enabled` from the effective global or
+per-plugin `allow_destructive_actions` policy and lets Codex enforce
+destructive tool metadata from its native app tool annotations. The `_default`
+app config is disabled with `open_world_enabled: false`. Enabled plugin apps
+are emitted with `open_world_enabled: true`; Nodmix does not expose a separate
+plugin open-world policy knob and does not maintain per-plugin destructive
+tool-name deny lists.
+
+Tool approval mode is automatic by default for plugin apps so non-destructive
+read tools can run without a same-thread approval UI. Destructive tools remain
+controlled by each app's `destructive_enabled` policy.
+
+## Destructive action policy
+
+Destructive plugin elicitations are allowed by default for migrated Codex
+plugins, while unsafe schemas and ambiguous ownership still fail closed:
+
+- Global `allow_destructive_actions` defaults to `true`.
+- Per-plugin `allow_destructive_actions` overrides the global policy for that
+  plugin.
+- When policy is `false`, Nodmix returns a deterministic decline.
+- When policy is `true`, Nodmix auto-accepts only safe schemas it can map to
+  an approval response, such as a boolean approve field.
+- Missing plugin identity, ambiguous ownership, a missing turn id, a wrong turn
+  id, or an unsafe elicitation schema declines instead of prompting.
+
+## Troubleshooting
+
+**`auth_required`:** migration installed the plugin, but one of its apps still
+needs authentication. The explicit plugin entry is written disabled until you
+reauthorize and enable it.
+
+**`app_inaccessible`, `app_disabled`, or `app_missing`:**
+migration did not install the plugin because the source Codex app inventory did
+not show all owned apps as present, enabled, and accessible while
+`--verify-plugin-apps` was set. Reauthorize or enable the app in Codex, then
+rerun migration with `--verify-plugin-apps`.
+
+**`app_inventory_unavailable`:** migration did not install the plugin because
+strict source app verification was requested and source Codex app inventory
+refresh failed. Fix source Codex app-server access or retry without
+`--verify-plugin-apps` if you accept the faster account-gated plan.
+
+**`codex_subscription_required`:** migration did not install the app-backed
+plugin because the source Codex app-server account was not logged in with a
+ChatGPT subscription account. Log in to the Codex app with subscription auth,
+then rerun migration.
+
+**`codex_account_unavailable`:** migration did not install the app-backed plugin
+because the source Codex app-server account could not be read. Fix source Codex
+app-server auth or rerun with `--verify-plugin-apps` if you want source app
+inventory to decide eligibility when account lookup fails.
+
+**`marketplace_missing` or `plugin_missing`:** the target Codex app-server
+cannot see the expected `openai-curated` marketplace or plugin. Rerun migration
+against the target runtime or inspect Codex app-server plugin status.
+
+**`app_inventory_missing` or `app_inventory_stale`:** app readiness came from an
+empty or stale cache. Nodmix schedules an async refresh and excludes plugin
+apps until ownership and readiness are known.
+
+**`app_ownership_ambiguous`:** app inventory only matched by display name, so
+the app is not exposed to the Codex thread.
+
+**Config changed but the agent cannot see the plugin:** use `/codex plugins
+list` to confirm the configured state, then use `/new` or `/reset`. Existing
+Codex thread bindings keep the app config they started with until Nodmix
+establishes a new harness session or replaces a stale binding.
+
+**Destructive action is declined:** check the global and per-plugin
+`allow_destructive_actions` values. Even when policy is true, unsafe elicitation
+schemas and ambiguous plugin identity still fail closed.
+
+## Related
+
+- [Codex harness](/plugins/codex-harness)
+- [Codex harness reference](/plugins/codex-harness-reference)
+- [Codex harness runtime](/plugins/codex-harness-runtime)
+- [Configuration reference](/gateway/configuration-reference#codex-harness-plugin-config)
+- [Migrate CLI](/cli/migrate)

package/docs/plugins/community.md

@@ -0,0 +1,77 @@
+---
+summary: "Find and publish community-maintained Nodmix plugins"
+read_when:
+  - You want to find third-party Nodmix plugins
+  - You want to publish or list your own plugin on ClawHub
+title: "Community plugins"
+doc-schema-version: 1
+---
+
+Community plugins are third-party packages that extend Nodmix with channels,
+tools, providers, hooks, or other capabilities. Use [ClawHub](/clawhub) as the
+primary discovery surface for public community plugins.
+
+## Find plugins
+
+Search ClawHub from the CLI:
+
+```bash
+nodmix plugins search "calendar"
+```
+
+Install a ClawHub plugin with an explicit source prefix:
+
+```bash
+nodmix plugins install clawhub:<package-name>
+```
+
+npm remains a supported direct-install path during the launch cutover:
+
+```bash
+nodmix plugins install npm:<package-name>
+```
+
+Use [Manage plugins](/plugins/manage-plugins) for common install, update,
+inspect, and uninstall examples. Use [`nodmix plugins`](/cli/plugins) for the
+full command reference and source-selection rules.
+
+## Publish plugins
+
+Publish public community plugins on ClawHub when you want Nodmix users to
+discover and install them. ClawHub owns the live package listing, release
+history, scan status, and install hints; the docs do not maintain a static
+third-party plugin catalog.
+
+```bash
+clawhub package publish your-org/your-plugin --dry-run
+clawhub package publish your-org/your-plugin
+```
+
+Before publishing, make sure the plugin has package metadata, a plugin manifest,
+setup docs, and a clear maintenance owner. ClawHub validates owner scope,
+package name, version, file limits, and source metadata before it creates a
+release, then keeps new releases hidden from normal install and download
+surfaces until review and verification finish.
+
+Use this checklist before you publish:
+
+| Requirement          | Why                                                 |
+| -------------------- | --------------------------------------------------- |
+| Published on ClawHub | Users need `nodmix plugins install` hints to work |
+| Public GitHub repo   | Source review, issue tracking, transparency         |
+| Setup and usage docs | Users need to know how to configure it              |
+| Active maintenance   | Recent updates or responsive issue handling         |
+
+Use these pages for the full publishing contract:
+
+- [ClawHub publishing](/clawhub/publishing) explains owners, scopes, releases,
+  review, package validation, and package transfer.
+- [Building plugins](/plugins/building-plugins) shows the plugin package shape
+  and first publish workflow.
+- [Plugin manifest](/plugins/manifest) defines native plugin manifest fields.
+
+## Related
+
+- [Plugins](/tools/plugin) - install, configure, restart, and troubleshoot
+- [Manage plugins](/plugins/manage-plugins) - command examples
+- [ClawHub publishing](/clawhub/publishing) - publish and release rules

package/docs/plugins/compatibility.md

@@ -0,0 +1,164 @@
+---
+summary: "Plugin compatibility contracts, deprecation metadata, and migration expectations"
+title: "Plugin compatibility"
+read_when:
+  - You maintain an Nodmix plugin
+  - You see a plugin compatibility warning
+  - You are planning a plugin SDK or manifest migration
+---
+
+Nodmix keeps older plugin contracts wired through named compatibility
+adapters before removing them. This protects existing bundled and external
+plugins while the SDK, manifest, setup, config, and agent runtime contracts
+evolve.
+
+## Compatibility registry
+
+Plugin compatibility contracts are tracked in the core registry at
+`src/plugins/compat/registry.ts`.
+
+Each record has:
+
+- a stable compatibility code
+- status: `active`, `deprecated`, `removal-pending`, or `removed`
+- owner: SDK, config, setup, channel, provider, plugin execution, agent runtime,
+  or core
+- introduction and deprecation dates when applicable
+- replacement guidance
+- docs, diagnostics, and tests that cover the old and new behavior
+
+The registry is the source for maintainer planning and future plugin inspector
+checks. If a plugin-facing behavior changes, add or update the compatibility
+record in the same change that adds the adapter.
+
+Doctor repair and migration compatibility is tracked separately at
+`src/commands/doctor/shared/deprecation-compat.ts`. Those records cover old
+config shapes, install-ledger layouts, and repair shims that may need to stay
+available after the runtime compatibility path is removed.
+
+Release sweeps should check both registries. Do not delete a doctor migration
+just because the matching runtime or config compatibility record expired; first
+verify there is no supported upgrade path that still needs the repair. Also
+revalidate each replacement annotation during release planning because plugin
+ownership and config footprint can change as providers and channels move out of
+core.
+
+## Plugin inspector package
+
+The plugin inspector should live outside the core Nodmix repo as a separate
+package/repository backed by the versioned compatibility and manifest
+contracts.
+
+The day-one CLI should be:
+
+```sh
+nodmix-plugin-inspector ./my-plugin
+```
+
+It should emit:
+
+- manifest/schema validation
+- the contract compatibility version being checked
+- install/source metadata checks
+- cold-path import checks
+- deprecation and compatibility warnings
+
+Use `--json` for stable machine-readable output in CI annotations. Nodmix
+core should expose contracts and fixtures the inspector can consume, but should
+not publish the inspector binary from the main `nodmix` package.
+
+### Maintainer acceptance lane
+
+Use Crabbox-backed Blacksmith Testbox for the installable-package acceptance
+lane when validating the external inspector against Nodmix plugin packages.
+Run it from a clean Nodmix checkout after the package is built:
+
+```sh
+pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @nodmix/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
+pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @nodmix/plugin-inspector@0.1.0 -- ./extensions/discord --json"
+pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @nodmix/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
+```
+
+Keep this lane opt-in for maintainers because it installs an external npm
+package and may inspect plugin packages cloned outside the repo. The local repo
+guards cover the SDK export map, compatibility registry metadata, deprecated
+SDK-import burn-down, and bundled extension import boundaries; Testbox inspector
+proof covers the package as external plugin authors consume it.
+
+## Deprecation policy
+
+Nodmix should not remove a documented plugin contract in the same release
+that introduces its replacement.
+
+The migration sequence is:
+
+1. Add the new contract.
+2. Keep the old behavior wired through a named compatibility adapter.
+3. Emit diagnostics or warnings when plugin authors can act.
+4. Document the replacement and timeline.
+5. Test both old and new paths.
+6. Wait through the announced migration window.
+7. Remove only with explicit breaking-release approval.
+
+Deprecated records must include a warning start date, replacement, docs link,
+and final removal date no more than three months after the warning starts. Do
+not add a deprecated compatibility path with an open-ended removal window unless
+maintainers explicitly decide it is permanent compatibility and mark it `active`
+instead.
+
+## Current compatibility areas
+
+Current compatibility records include:
+
+- legacy broad SDK imports such as `nodmix/plugin-sdk/compat`
+- legacy hook-only plugin shapes and `before_agent_start`
+- legacy `api.on("deactivate", ...)` cleanup hook names while plugins migrate to
+  `gateway_stop`
+- legacy `activate(api)` plugin entrypoints while plugins migrate to
+  `register(api)`
+- legacy SDK aliases such as `nodmix/extension-api`,
+  `nodmix/plugin-sdk/channel-runtime`, `nodmix/plugin-sdk/command-auth`
+  status builders, `nodmix/plugin-sdk/test-utils` (replaced by focused
+  `nodmix/plugin-sdk/*` test subpaths), and the `ClawdbotConfig` /
+  `NodmixSchemaType` type aliases
+- bundled plugin allowlist and enablement behavior
+- legacy provider/channel env-var manifest metadata
+- legacy provider plugin hooks and type aliases while providers move to
+  explicit catalog, auth, thinking, replay, and transport hooks
+- legacy runtime aliases such as `api.runtime.taskFlow`,
+  `api.runtime.subagent.getSession`, `api.runtime.stt`, and deprecated
+  `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
+- legacy memory-plugin split registration while memory plugins move to
+  `registerMemoryCapability`
+- legacy channel SDK helpers for native message schemas, mention gating,
+  inbound envelope formatting, and approval capability nesting
+- legacy channel route key and comparable-target helper aliases while plugins
+  move to `nodmix/plugin-sdk/channel-route`
+- activation hints that are being replaced by manifest contribution ownership
+- `setup-api` runtime fallback while setup descriptors move to cold
+  `setup.requiresRuntime: false` metadata
+- provider `discovery` hooks while provider catalog hooks move to
+  `catalog.run(...)`
+- channel `showConfigured` / `showInSetup` metadata while channel packages move
+  to `nodmix.channel.exposure`
+- legacy runtime-policy config keys while doctor migrates operators to
+  `agentRuntime`
+- generated bundled channel config metadata fallback while registry-first
+  `channelConfigs` metadata lands
+- persisted plugin registry disable and install-migration env flags while
+  repair flows migrate operators to `nodmix plugins registry --refresh` and
+  `nodmix doctor --fix`
+- legacy plugin-owned web search, web fetch, and x_search config paths while
+  doctor migrates them to `plugins.entries.<plugin>.config`
+- legacy `plugins.installs` authored config and bundled plugin load-path
+  aliases while install metadata moves into the state-managed plugin ledger
+
+New plugin code should prefer the replacement listed in the registry and in the
+specific migration guide. Existing plugins can keep using a compatibility path
+until the docs, diagnostics, and release notes announce a removal window.
+
+## Release notes
+
+Release notes should include upcoming plugin deprecations with target dates and
+links to migration docs. That warning needs to happen before a compatibility
+path moves to `removal-pending` or `removed`.

package/docs/plugins/dependency-resolution.md

@@ -0,0 +1,143 @@
+---
+summary: "How Nodmix installs plugin packages and resolves plugin dependencies"
+read_when:
+  - You are debugging plugin package installs
+  - You are changing plugin startup, doctor, or package-manager install behavior
+  - You are maintaining packaged Nodmix installs or bundled plugin manifests
+title: "Plugin dependency resolution"
+sidebarTitle: "Dependencies"
+---
+
+Nodmix keeps plugin dependency work at install/update time. Runtime loading
+does not run package managers, repair dependency trees, or mutate the Nodmix
+package directory.
+
+## Responsibility split
+
+Plugin packages own their dependency graph:
+
+- runtime dependencies live in the plugin package `dependencies` or
+  `optionalDependencies`
+- SDK/core imports are peer or supplied Nodmix imports
+- local development plugins bring their own already-installed dependencies
+- npm and git plugins are installed into Nodmix-owned package roots
+
+Nodmix owns only the plugin lifecycle:
+
+- discover the plugin source
+- install or update the package when explicitly requested
+- record the install metadata
+- load the plugin entrypoint
+- fail with an actionable error when dependencies are missing
+
+## Install roots
+
+Nodmix uses stable per-source roots:
+
+- npm packages install under `~/.nodmix/npm`
+- git packages clone under `~/.nodmix/git`
+- local/path/archive installs are copied or referenced without dependency repair
+
+npm installs run in the npm root with:
+
+```bash
+cd ~/.nodmix/npm
+npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund
+```
+
+`nodmix plugins install npm-pack:<path.tgz>` uses that same managed npm root
+for a local npm-pack tarball. Nodmix reads the tarball's npm metadata, adds it
+to the managed root as a copied `file:` dependency, runs the normal npm install,
+and then verifies the installed lockfile metadata before trusting the plugin.
+This is intended for package-acceptance and release-candidate proof where a
+local pack artifact should behave like the registry artifact it simulates.
+
+npm may hoist transitive dependencies to `~/.nodmix/npm/node_modules` beside
+the plugin package. Nodmix scans the managed npm root before trusting the
+install and uses npm to remove npm-managed packages during uninstall, so hoisted
+runtime dependencies stay inside the managed cleanup boundary.
+
+Plugins that import `nodmix/plugin-sdk/*` declare `nodmix` as a peer
+dependency. Nodmix does not let npm install a separate registry copy of the
+host package into the managed root, because stale host packages can affect npm
+peer resolution during later plugin installs. Managed npm installs skip npm peer
+resolution/materialization for the shared root and Nodmix reasserts
+plugin-local `node_modules/nodmix` links for installed packages that declare
+the host peer after install, update, or uninstall.
+
+git installs clone or refresh the repository, then run:
+
+```bash
+npm install --omit=dev --ignore-scripts --no-audit --no-fund
+```
+
+The installed plugin then loads from that package directory, so package-local
+and parent `node_modules` resolution works the same way it does for a normal
+Node package.
+
+## Local plugins
+
+Local plugins are treated as developer-controlled directories. Nodmix does not
+run `npm install`, `pnpm install`, or dependency repair for them. If a local
+plugin has dependencies, install them in that plugin before loading it.
+
+Third-party TypeScript local plugins can use the emergency Jiti path. Packaged
+JavaScript plugins and bundled internal plugins load through native
+import/require instead of Jiti.
+
+## Startup and reload
+
+Gateway startup and config reload never install plugin dependencies. They read
+the plugin install records, compute the entrypoint, and load it.
+
+If a dependency is missing at runtime, the plugin fails to load and the error
+should point the operator to an explicit fix:
+
+```bash
+nodmix plugins update <id>
+nodmix plugins install <source>
+nodmix doctor --fix
+```
+
+`doctor --fix` can clean legacy Nodmix-generated dependency state and recover
+downloadable plugins that are missing from the local install records when config
+references them. Doctor does not repair dependencies for an already-installed
+local plugin.
+
+## Bundled plugins
+
+Lightweight and core-critical bundled plugins are shipped as part of Nodmix.
+They should either have no heavy runtime dependency tree or be moved out to a
+downloadable package on ClawHub/npm.
+
+For the current generated list of plugins that ship in the core package, install
+externally, or stay source-only, see [Plugin inventory](/plugins/plugin-inventory).
+
+Bundled plugin manifests must not request dependency staging. Large or optional
+plugin functionality should be packaged as a normal plugin and installed through
+the same npm/git/ClawHub path as third-party plugins.
+
+In source checkouts, Nodmix treats the repository as a pnpm monorepo. After
+`pnpm install`, bundled plugins load from `extensions/<id>` so package-local
+workspace dependencies are available and edits are picked up directly. Source
+checkout development is pnpm-only; plain `npm install` at the repository root is
+not a supported way to prepare bundled plugin dependencies.
+
+| Install shape                    | Bundled plugin location               | Dependency owner                                                     |
+| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
+| `npm install -g nodmix`        | Built runtime tree inside the package | Nodmix package and explicit plugin install/update/doctor flows     |
+| Git checkout plus `pnpm install` | `extensions/<id>` workspace packages  | The pnpm workspace, including each plugin package's own dependencies |
+| `nodmix plugins install ...`   | Managed npm/git/ClawHub plugin root   | The plugin install/update flow                                       |
+
+## Legacy cleanup
+
+Older Nodmix versions generated bundled-plugin dependency roots at startup or
+during doctor repair. Current doctor cleanup removes those stale directories and
+symlinks when `--fix` is used, including old `plugin-runtime-deps` roots, global
+Node-prefix package symlinks that point at pruned `plugin-runtime-deps` targets,
+`.nodmix-runtime-deps*` manifests, generated plugin `node_modules`, install
+stage directories, and package-local pnpm stores. Packaged postinstall also
+removes those global symlinks before pruning the legacy target roots so upgrades
+do not leave dangling ESM package imports.
+
+These paths are legacy debris only. New installs should not create them.