feat(controller-integration): enhance skill descriptions for clarity

Author: NicolasMassart

domains/coding/skills/controller-integration/repos/metamask-extension.md

@@ -15,21 +15,28 @@ The integration surface is `app/scripts/messenger-client-init/` (the pattern is
 | Stateless service | No persisted state (e.g. an API service) | Same as modular, minus state steps |
 | Wallet-managed | Name is one of: AccountsController, ApprovalController, ConnectivityController, KeyringController, NetworkController, RemoteFeatureFlagController, StorageService | `this.wallet.getInstance('<Name>')` — construction happens inside `@metamask/wallet` |
 
+Independently of the path above, the controller class itself comes from one of two sources — the `messenger-client-init/` wiring in §3 is identical either way, only step 1 (and where types are imported from) differs:
+
+| Source | When | Where the class lives |
+|---|---|---|
+| npm package | Controller is owned/shared outside the extension (most new controllers) | `@metamask/<name>-controller`, imported as a dependency |
+| Repo-local | Controller is extension-only | `app/scripts/controllers/<name>/` (class + a `<name>-controller.types.ts` exporting the messenger type) — e.g. `app/scripts/controllers/rewards/rewards-controller.ts` |
+
 ## 2. Canonical examples (read, don't guess)
 
 | Controller | Copy for |
 |---|---|
-| `app/scripts/messenger-client-init/geolocation-controller-init.ts` + `messengers/geolocation-controller-messenger.ts` (+ both `.test.ts`) | Default pattern: init fn, default-state hydration, `api` methods, minimal messenger, tests |
+| `app/scripts/messenger-client-init/geolocation-controller-init.ts` + `messengers/geolocation-controller-messenger.ts` (+ both `.test.ts`) | Default pattern (npm-package controller): init fn, default-state hydration, `api` methods, minimal messenger, tests |
 | `app/scripts/messenger-client-init/transaction-pay-controller-init.ts` + `messengers/transaction-pay-controller-messenger.ts` | Separate init messenger used inside constructor callbacks, heavy cross-controller delegation |
-| `app/scripts/messenger-client-init/rewards-controller-init.ts` + `messengers/rewards-controller-messenger.ts` | Remote-feature-flag gating via init messenger |
+| `app/scripts/controllers/rewards/rewards-controller.ts` (+ `rewards-controller.types.ts` exporting `RewardsControllerMessenger`) + `app/scripts/messenger-client-init/rewards-controller-init.ts` + `messengers/rewards-controller-messenger.ts` | Repo-local controller pattern, plus remote-feature-flag gating via init messenger. The init/messenger files are indistinguishable in shape from the npm-package case — only the class import path differs |
 | `PerpsController` entries in `app/scripts/metamask-controller.js` + `shared/lib/environment.ts` | Build-flag gating (conditional init-map spread) |
 | `app/scripts/messenger-client-init/data-deletion-service-init.ts` | Stateless service |
 
 ## 3. Ordered steps
 
 | # | File | Action |
 |---|---|---|
-| 1 | `package.json` | `yarn add @metamask/<name>-controller`, then `yarn lint:lockfile:dedupe:fix && yarn allow-scripts auto && yarn lavamoat:auto && yarn attributions:generate` (skip if repo-local) |
+| 1 | `package.json`, or `app/scripts/controllers/<name>/` | **npm package**: `yarn add @metamask/<name>-controller`, then `yarn lint:lockfile:dedupe:fix && yarn allow-scripts auto && yarn lavamoat:auto && yarn attributions:generate`. **Repo-local**: create the folder with the controller class and a `<name>-controller.types.ts` exporting the messenger type — mirror `app/scripts/controllers/rewards/` — no dependency commands needed |
 | 2 | `app/scripts/messenger-client-init/messengers/<name>-controller-messenger.ts` | Create `getXControllerMessenger` (skeleton below). Add `getXControllerInitMessenger` (namespace `'XControllerInit'`) only if the init fn itself needs actions/events beyond the controller's messenger type |
 | 3 | `app/scripts/messenger-client-init/messengers/<name>-controller-messenger.test.ts` | `expect(messenger).toBeInstanceOf(Messenger)`; optionally assert delegation via a `delegate` spy |
 | 4 | `app/scripts/messenger-client-init/messengers/index.ts` | Export the factory fns; add to `MESSENGER_FACTORIES`: `{ getMessenger, getInitMessenger: noop }` (lodash `noop`) or the real init-messenger fn |

domains/coding/skills/controller-integration/repos/metamask-mobile.md

@@ -13,25 +13,34 @@ parent: controller-integration
 | Stateless service | No persisted state (e.g. an API service) | Same as modular, minus state steps |
 | Wallet-owned | Name is one of: AccountsController, ApprovalController, ConnectivityController, KeyringController, NetworkController, RemoteFeatureFlagController, StorageService | `this.#wallet.getInstance('<Name>')` — never an init function |
 
+Independently of the path above, the controller class itself comes from one of two sources — the wiring steps in §3 are identical either way, only step 1 (and where types are imported from) differs:
+
+| Source | When | Where the class lives |
+|---|---|---|
+| npm package | Controller is owned/shared outside mobile (most new controllers) | `@metamask/<name>-controller`, imported as a dependency |
+| Repo-local | Controller is mobile-only | `app/core/Engine/controllers/<name>-controller/` (own folder: class, `types.ts`, default state, init fn) — e.g. `card-controller/` (`CardController`), `rewards-controller/` (`RewardsController`) |
+
 ## 2. Canonical examples (read, don't guess)
 
 | Controller | Copy for |
 |---|---|
-| `app/core/Engine/controllers/config-registry-controller-init.ts` + `app/core/Engine/messengers/config-registry-controller-messenger.ts` | Default pattern: init fn, messenger + delegate, tests, selector, fixture entry |
+| `app/core/Engine/controllers/config-registry-controller-init.ts` + `app/core/Engine/messengers/config-registry-controller-messenger.ts` | Default pattern (npm-package controller): init fn, messenger + delegate, tests, selector, fixture entry |
 | `app/core/Engine/controllers/money-account-upgrade-controller-init.ts` + `.../money-account-upgrade-controller-messenger.ts` | Init messenger, cross-controller delegation, remote-flag init-time gating |
+| `app/core/Engine/controllers/card-controller/` (`CardController.ts`, `types.ts`, `index.ts` as init) + `app/core/Engine/messengers/card-controller-messenger.ts` | Repo-local controller pattern: class + messenger type + default state co-located in one folder, init fn in the folder's `index.ts` |
+| `app/core/Engine/controllers/rewards-controller/` (`RewardsController.ts`) + `app/core/Engine/messengers/rewards-controller-messenger.ts` | Repo-local controller with remote-flag gating |
 | `app/features/SampleFeature/controllers/sample-petnames-controller-init.ts` | `ONLY_INCLUDE_IF(sample-feature)` fencing only — its tests/selector lag the pattern, do not copy those |
 
 ## 3. Ordered steps
 
 | # | File | Action |
 |---|---|---|
-| 1 | `package.json` | `yarn add @metamask/<name>-controller` (skip if repo-local) |
+| 1 | `package.json`, or `app/core/Engine/controllers/<name>-controller/` | **npm package**: `yarn add @metamask/<name>-controller`. **Repo-local**: create the folder with the controller class (extend `BaseController`), `types.ts` (state, messenger type, `ControllerStateChangeEvent`-based Events union), and default state — mirror `card-controller/` or `rewards-controller/` |
 | 2 | `app/core/Engine/messengers/<name>-controller-messenger.ts` | Create `getXControllerMessenger` (skeleton below). Add `getXControllerInitMessenger` too if init-time gating is needed (own namespace `<Name>Initialization`) |
 | 3 | `app/core/Engine/messengers/<name>-controller-messenger.test.ts` | `expect(messenger).toBeInstanceOf(Messenger)` |
 | 4 | `app/core/Engine/messengers/index.ts` | Add to `MESSENGER_FACTORIES`: `{ getMessenger, getInitMessenger: noop }` (or the real init messenger fn) |
-| 5 | `app/core/Engine/types.ts` | Add to `GlobalActions`, `GlobalEvents`, `MessengerClients`, `EngineState`, `MessengerClientsToInitialize` (+ `RequiredControllers`/`OptionalControllers` if optional) |
-| 6 | `app/core/Engine/controllers/<name>-controller-init.ts` | Create `MessengerClientInitFunction` (skeleton below), return `{ controller }` only |
-| 7 | `app/core/Engine/controllers/<name>-controller-init.test.ts` | Use `buildMessengerClientInitRequestMock` from `app/core/Engine/utils/test-utils.ts` |
+| 5 | `app/core/Engine/types.ts` | Add to `GlobalActions`, `GlobalEvents`, `MessengerClients`, `EngineState`, `MessengerClientsToInitialize` (+ `RequiredControllers`/`OptionalControllers` if optional). Import the controller/messenger types from `@metamask/<name>-controller` (package) or from the local `controllers/<name>-controller/types.ts` (repo-local) |
+| 6 | `app/core/Engine/controllers/<name>-controller-init.ts`, or `app/core/Engine/controllers/<name>-controller/index.ts` for a repo-local controller | Create `MessengerClientInitFunction` (skeleton below), return `{ controller }` only |
+| 7 | `app/core/Engine/controllers/<name>-controller-init.test.ts` (co-located `index.test.ts` if repo-local) | Use `buildMessengerClientInitRequestMock` from `app/core/Engine/utils/test-utils.ts` |
 | 8 | `app/core/Engine/constants.ts` | Append `'<Name>:stateChange'` to `BACKGROUND_STATE_CHANGE_EVENT_NAMES`. ⚠️ Copy the exact event name from the package's `Events` type — some emit `:stateChanged` |
 | 9 | `app/core/Engine/Engine.ts` | (a) import init fn (b) add to `initFunctions` **after** every controller it depends on — insertion order is init order (c) add to `this.context` (d) add to **both** the destructuring and return object of `get state()` |
 | 10 | `app/util/test/initial-background-state.json` | Add default state (run step in §7 verify to get the exact expected value) |
@@ -104,7 +113,7 @@ export const xControllerInit: MessengerClientInitFunction<
 | Controller missing from `Engine.state` getter | `UPDATE_BG_STATE` writes `undefined` into Redux for that key |
 | Calling a non-delegated action | Runtime throw from `@metamask/messenger` at call time |
 | Dependency read before it's initialized | `Error: Messenger client requested before it was initialized: <Name>` — move the entry later in `initFunctions` |
-| Controller metadata has no `persist: true` key | Redux updates but state never survives restart (silently skipped, logged only) |
+| Controller metadata has no `persist: true` key | Redux updates but state never survives restart (silently skipped, logged only). For a repo-local controller this metadata is authored by you in the class's own `metadata` object, not inherited from a package |
 
 ## 7. Verify
 

domains/coding/skills/controller-integration/skill.md

@@ -1,11 +1,13 @@
 ---
 name: controller-integration
 description: >
-  Wire a new or existing controller into the MetaMask Mobile Engine or the
-  MetaMask Extension background. Use this skill when: adding a controller to
-  Engine or to the extension's messenger-client init, creating a controller
-  init function or messenger, delegating actions/events between controllers,
-  adding a controller to EngineState/Engine.context or to MESSENGER_FACTORIES
-  and the MessengerClient union, or debugging a controller whose state never
-  reaches Redux/the UI or resets on restart.
+  Wire a new or existing controller — whether imported from a
+  `@metamask/*-controller` npm package or defined locally in the repo — into
+  the MetaMask Mobile Engine or the MetaMask Extension background. Use this
+  skill when: adding a controller to Engine or to the extension's
+  messenger-client init, creating a controller init function or messenger,
+  delegating actions/events between controllers, adding a controller to
+  EngineState/Engine.context or to MESSENGER_FACTORIES and the
+  MessengerClient union, or debugging a controller whose state never reaches
+  Redux/the UI or resets on restart.
 ---