Relocate cloud-deployment examples under ai/ to unbreak build-all

Context

npm run build-all fails with a webpack module-resolution error:

ERROR in ./examples/cloud-deployment/minimal-external-workspace/src/ProtoSource.mjs 4:0-85
Module not found: Error: Can't resolve 'neo.mjs/ai/services/knowledge-base/source/Base.mjs'
 @ ./src/worker/Data.mjs 87:31-92:13

Surfaced by @tobiu during a fresh-worktree build-all on 2026-05-31.

The Problem

examples/cloud-deployment/ is a Right-hemisphere (Agent OS / Node.js) example tree — its minimal-external-workspace/src/ProtoSource.mjs imports node:fs, neo.mjs/ai/services/knowledge-base/source/Base.mjs, and neo.mjs/ai/mcp/server/knowledge-base/config.mjs. Per learn/benefits/ArchitectureOverview.md, ai/ is the Agent-OS hemisphere and is deliberately excluded from the browser runtime bundle.

But the tree lives under the Left-hemisphere examples/ directory. src/worker/Data.mjs's lazy dynamic-import context (createInstance) globs `(?:apps|docs/app|examples|src/data)/.*.mjs# Relocate cloud-deployment examples under ai/ to unbreak build-all

Context

npm run build-all fails with a webpack module-resolution error:

ERROR in ./examples/cloud-deployment/minimal-external-workspace/src/ProtoSource.mjs 4:0-85
Module not found: Error: Can't resolve 'neo.mjs/ai/services/knowledge-base/source/Base.mjs'
 @ ./src/worker/Data.mjs 87:31-92:13

Surfaced by @tobiu during a fresh-worktree build-all on 2026-05-31.

The Problem

examples/cloud-deployment/ is a Right-hemisphere (Agent OS / Node.js) example tree — its minimal-external-workspace/src/ProtoSource.mjs imports node:fs, neo.mjs/ai/services/knowledge-base/source/Base.mjs, and neo.mjs/ai/mcp/server/knowledge-base/config.mjs. Per learn/benefits/ArchitectureOverview.md, ai/ is the Agent-OS hemisphere and is deliberately excluded from the browser runtime bundle.

But the tree lives under the Left-hemisphere examples/ directory. src/worker/Data.mjs's lazy dynamic-import context (createInstance) globs and excludes (buildScripts|dist|node_modules(?!neo.mjs)|ai/|server.mjs|…). So webpack tries to bundle ProtoSource.mjs into the runtime — and chokes on its neo.mjs/ai/... import, which resolves into the bundle-excluded ai/ tree.

The import path itself is valid for Node (ai/services/knowledge-base/source/Base.mjs exists); the only defect is hemisphere-misplacement.

The Architectural Reality

• Offender: examples/cloud-deployment/minimal-external-workspace/src/ProtoSource.mjs — the sole left-hemisphere .mjs importing node:/neo.mjs/ai/ (verified by grep over examples/**/*.mjs). ProtoParser.mjs imports neo.mjs/src/core/Base.mjs (bundle-resolvable) but moves with the tree for cohesion.
• Webpack context: src/worker/Data.mjs:86-92 — webpackInclude/webpackExclude magic comments. ai/ is in the exclude list → relocating under ai/ removes the tree from the left-hemisphere scan.
• Target home ai/examples/ already exists and hosts Node Agent-OS scripts (db-backup.mjs, self-healing.mjs, test-*.mjs, …) — sibling-pattern match (structural-pre-flight fast-path).
• Internal imports are bare neo.mjs/... specifiers → move-safe (no relative-path breakage); only the workspace README.md's ./src/... examples are relative and stay valid.

The Fix

1. git mv examples/cloud-deployment ai/examples/cloud-deployment (preserves history; keeps the cohesive cloud-deployment grouping).
2. Update the doc references from examples/cloud-deployment → ai/examples/cloud-deployment (uniform transform): learn/agentos/DeploymentCookbook.md + learn/agentos/cloud-deployment/{Overview,HookWiring,CustomSources,PipelineWiring,CustomParsers,Day0Tutorial}.md.

Contract Ledger

Decision Record impact

aligned-with the Left/Right-hemisphere split in learn/benefits/ArchitectureOverview.md; aligned-with ADR 0014 (cloud-deployment topology + scheduler taxonomy). No ADR amendment.

Acceptance Criteria

• examples/cloud-deployment/ no longer exists; the tree lives under ai/examples/cloud-deployment/.
• npm run build-all no longer emits the ProtoSource.mjs "Can't resolve 'neo.mjs/ai/...'" error.
• All doc references resolve to the new path (no dangling examples/cloud-deployment links).
• No left-hemisphere examples/**/*.mjs imports node: or neo.mjs/ai/ (grep-verified).

Out of Scope

• Re-homing the doc guides themselves — they live under learn/agentos/cloud-deployment/ and stay there; only their links to the runnable example move.
• Changing ProtoSource.mjs / ProtoParser.mjs contents (imports already valid for Node).
• The portal /news/tickets dynamic-import error reported separately — its import chain is verified to fully resolve on dev post-#12266 (likely a stale local checkout).

Avoided Traps

• ❌ Adding ProtoSource.mjs to the webpack webpackExclude individually — symptom patch; leaves a Right-hemisphere example in the Left-hemisphere tree and invites recurrence.
• ❌ Rewriting the example to avoid ai/ imports — it is legitimately an Agent-OS Source example; the import is correct, the location is not.

Related

• Hemisphere model: learn/benefits/ArchitectureOverview.md.
• Example lineage: #11733 / #11726 / #11743 (cloud-deployment example + tenant ingestion).

Authored by Opus 4.8 (Claude Code).