docs(docs): record lazy-loading decision + add defensive spec (#2283)

Closes #2249.

Issue 2249 asked whether to keep or remove `"lazy": true` support in
package.json. Decision: keep. The feature is small (~15 lines in
PackageLoader), legitimately useful for third-party service-only
packages, and zero audit debt — no first-party package currently
qualifies, so we're not carrying adoption weight for an unused feature.

## What's already in place

- **Guide:** `web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/packages.mdx`
  has a dedicated `## Lazy loading` section and the `lazy` field is
  documented in the manifest reference (added in #2281).
- **Tests:** `vendor/wheels/tests/specs/packages/PackageLoaderSpec.cfc`
  already covers the happy path: eager-skip, `isPackageLoaded`, and
  on-demand instantiation via `getPackage()`.

## What this PR adds

- **CHANGELOG entry** under Unreleased / Changed documenting the
  retain-and-document decision, first-party audit result (no candidates),
  and pointer to the guide.
- **Defensive spec** for the `canBeLazy` gate: a package declaring
  `lazy: true` alongside `mixins: "controller"` must still be loaded
  eagerly — if the lazy flag were honored the mixin tables would be
  incomplete at boot. New fixture at `tests/_assets/packages/lazyignored/`.

## Audit of first-party packages

All six first-party packages declare `mixins: "controller"` and
therefore cannot be lazy-loaded (lazy requires mixins=none and no
middleware). No conversion work to do:

| Package | mixins | Candidate? |
|---|---|---|
| wheels-sentry | controller | no |
| wheels-hotwire | controller | no |
| wheels-basecoat | controller | no |
| wheels-legacy-adapter | controller | no |
| wheels-i18n | controller | no |
| wheels-seo-suite | controller | no |

The feature remains valid and tested for any future third-party
service-only package that benefits.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bpamiri

CHANGELOG.md

@@ -125,6 +125,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 - CI engine testing restructured: 42 jobs reduced to 8 via engine-grouped testing (#1939)
 - `wheels mcp wheels` MCP surface curated — 7 CLI-only commands (`mcp`, `d`, `new`, `console`, `start`, `stop`, `browser`) hidden from MCP `tools/list` via the `mcpHiddenTools()` convention (requires LuCLI 0.3.4+). All remain reachable as CLI subcommands. Tool count drops from 23 to 16 for agent consumers.
 - LuCLI stdio MCP (`wheels mcp wheels`) is now the canonical AI-agent surface for Wheels. `wheels mcp setup` generates `.mcp.json` and `.opencode.json` pointing at the stdio transport. No port or running dev server required. Updated templates: `cli/src/templates/McpConfig.json`, `app/snippets/McpConfig.json`, `tools/build/base/.mcp.json`, `tools/build/base/.opencode.json`.
+- Package lazy-loading (`"lazy": true` in `package.json`) retained and documented in the [Packages](web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/packages.mdx) guide. Audit of all six first-party packages (`wheels-sentry`, `wheels-hotwire`, `wheels-basecoat`, `wheels-legacy-adapter`, `wheels-i18n`, `wheels-seo-suite`) found no candidates — all provide controller mixins, which require eager load to populate the mixin tables. The feature remains valid for third-party service-only packages. Added a defensive test that a package declaring `lazy: true` alongside mixins or middleware is still loaded eagerly (the loader's existing `canBeLazy` gate). (#2249)
 
 ### Deprecated
 

vendor/wheels/tests/_assets/packages/lazyignored/lazyignored.cfc

@@ -0,0 +1,11 @@
+component {
+	public any function init() {
+		this.version = "1.0.0";
+		this.initialized = true;
+		return this;
+	}
+
+	public string function $lazyIgnoredHelper() {
+		return "lazyignored-eagerly-loaded";
+	}
+}

vendor/wheels/tests/_assets/packages/lazyignored/package.json

@@ -0,0 +1,9 @@
+{
+	"name": "wheels-lazyignored",
+	"version": "1.0.0",
+	"description": "Test fixture: lazy=true combined with mixins — lazy flag must be ignored, package must load eagerly so mixin tables are populated at boot.",
+	"lazy": true,
+	"provides": {
+		"mixins": "controller"
+	}
+}

vendor/wheels/tests/specs/packages/PackageLoaderSpec.cfc

@@ -446,6 +446,23 @@ component extends="wheels.WheelsTest" {
 					expect(loader.getPackages()).toHaveKey("lazypkg");
 				});
 
+				it("ignores lazy=true when the package also declares mixins", () => {
+					// Packages that contribute to mixin tables must load eagerly
+					// so the tables are complete by the time controllers/views
+					// reference the mixed-in methods. The `canBeLazy` gate in
+					// PackageLoader requires mixins=none AND no middleware.
+					var loader = new wheels.PackageLoader(
+						vendorPath = fixturesPath,
+						componentPrefix = componentPrefix
+					);
+					var pkgs = loader.getPackages();
+
+					// lazyignored declares lazy=true + mixins=controller;
+					// it should be eagerly loaded despite the lazy flag.
+					expect(pkgs).toHaveKey("lazyignored");
+					expect(pkgs.lazyignored.initialized).toBeTrue();
+				});
+
 			});
 
 			describe("Mixin collisions", () => {