- Channels are implementation under `src/channels/**`; plugin authors get SDK seams. Providers own auth/catalog/runtime hooks; core owns generic loop.

- Hot paths should carry prepared facts forward: provider id, model ref, channel id, target, capability family, attachment class. Do not rediscover with broad plugin/provider/channel/capability loaders.

- Do not fix repeated request-time discovery with scattered caches. Move the canonical fact earlier; reuse prepared runtime objects; delete duplicate lookup branches.

- Gateway/plugin metadata is process-stable: installs, manifests, catalogs, generated paths, bundled metadata. Changes require restart or explicit owner reload/install/doctor flow.

- Runtime hot paths: no freshness polling (`stat`/`realpath`/JSON reread/hash). Reuse current snapshots, install records, discovery, lookup tables, root scopes, resolved paths.

- Process-local metadata caches ok when lifecycle-owned and bounded/single-slot. Freshness exceptions need named owner + tests.

- Inline code comments: brief notes for tricky, bug-prone, or previously buggy logic.

- Gateway protocol changes: additive first; incompatible needs versioning/docs/client follow-through.

- Protocol version bumps: explicit owner confirmation only; never automatic/generated.

belongs to runtime resolution.

- Preserve manifest-first behavior: discovery, config validation, and setup

should work from metadata before plugin runtime executes.

- Cache concept: metadata stays fresh unless a caller owns an explicit

`PluginMetadataSnapshot`, `PluginLookUpTable`, or manifest registry for the

current flow. Do not add persistent metadata caches for discovery, manifest

registries, installed-index reconstruction, owner lookup, model suppression,

provider policy, public-artifact metadata, or similar control-plane answers.

Runtime loader, jiti/module, and dependency-artifact caches are the allowed

cache layer once code or installed artifacts are actually loaded.

- Cache concept: gateway plugin metadata is stable while gateway runs. Reuse

current snapshots, install records, discovery, lookup tables, and bounded

process caches; avoid per-call stat/read/hash freshness. Plugin metadata

changes require restart or explicit plugin owner reload/install/doctor flow.

No broad persistent caches; lifecycle-owned facts only, test-clearable.

- Keep loader behavior aligned with the documented Plugin SDK and manifest

contracts. Do not create private backdoors that bundled plugins can use but

external plugins cannot.