---
id: 12270
title: Relocate cloud-deployment examples under ai/ to unbreak build-all
state: CLOSED
labels:
  - bug
  - ai
  - build
assignees:
  - neo-opus-ada
createdAt: '2026-05-31T19:51:17Z'
updatedAt: '2026-06-01T10:49:03Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12270'
author: neo-opus-ada
commentsCount: 4
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-01T10:49:03Z'
---
# 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$` 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

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `examples/cloud-deployment/**` location | ArchitectureOverview.md hemisphere model + `src/worker/Data.mjs` bundle glob | relocate to `ai/examples/cloud-deployment/**` (Right-hemisphere home) | n/a — pure move | the cloud-deployment guides | `build-all` webpack error; glob include/exclude; `ai/services/.../Base.mjs` exists on disk |

## 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).

## Timeline

- 2026-05-31T19:51:18Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-31T19:51:19Z @neo-opus-ada added the `bug` label
- 2026-05-31T19:51:19Z @neo-opus-ada added the `ai` label
- 2026-05-31T19:51:19Z @neo-opus-ada added the `build` label
- 2026-05-31T20:08:44Z @neo-opus-ada cross-referenced by PR #12272
### @neo-opus-ada - 2026-05-31T20:10:51Z

**Input from Opus 4.8 (Claude Code):**

> ❋ **Scope note — PR #12272 resolves this with a second, necessary fix beyond the filed "relocate" scope.**
> 
> During verification (`buildThreads -f` prod data-worker), the relocation alone did **not** clear `build-all`: webpack's `src/worker` lazy-import globs were scanning **sibling git worktrees** under `.claude/worktrees/` (~18 present; several on old branches still carrying the old `examples/cloud-deployment/` layout). So `ProtoSource.mjs` was still bundled from those siblings.
> 
> Operator-confirmed fix (Part 2): added a `.claude/` exclusion token to the `webpackExclude` magic comment in all 9 lazy-import contexts across `src/worker/{Data,Canvas,Task,App}.mjs` — mirroring the existing `node_modules` / `ai/` exclusions. This is the part that actually unblocks a main-repo `build-all`.
> 
> PR #12272 carries both parts (relocation + worktree exclusion) since the relocation alone is an intermediate-insecure state (build still red). Verified: prod data worker `compiled successfully in 502ms` + deterministic include/exclude regex proof.

### @neo-opus-ada - 2026-05-31T20:30:47Z

**Input from Opus 4.8 (Claude Code):**

> ❋ **Residual annotation (per @neo-gpt cycle-1 review of PR #12272, evidence-ladder durability):**
> 
> `[L3-deferred — operator handoff needed]` **operator main-repo `build-all` confirmation.**
> 
> PR #12272 fixes this at two evidence levels:
> - **Part 1 (relocation)** — L2 high-confidence: the operator-reported failing file `./examples/cloud-deployment/.../ProtoSource.mjs` (the main repo's *own* `examples/` tree) is moved out of the worker lazy-glob scan entirely.
> - **Part 2 (`.claude/` worktree exclusion)** — L2 mechanism-proof (deterministic include/exclude regex + clean prod data-worker compile), but the exact path shape webpack emits for sibling worktrees in the operator's *main-repo* `insideNeo=true` build could not be reproduced in a Claude worktree (no nested `.claude/worktrees/`).
> 
> PR #12272 therefore uses `Refs #12270` (not `Resolves`) so this ticket is **not** auto-closed on merge. **Close trigger:** operator runs `npm run build-all` on the main repo (with sibling worktrees present) and confirms no `ProtoSource.mjs` "Can't resolve 'neo.mjs/ai/...'" error → then close #12270.

- 2026-05-31T20:44:09Z @tobiu referenced in commit `1bb6657` - "fix(build): move cloud-deployment examples to ai/ + exclude .claude from worker import globs (#12270) (#12272)

Right-hemisphere (Agent OS / Node.js) cloud-deployment examples lived under the Left-hemisphere examples/ tree. webpack's src/worker lazy dynamic-import globs include examples/ and exclude ai/, so they bundled minimal-external-workspace/src/ProtoSource.mjs (node: + neo.mjs/ai imports) into the runtime and failed build-all.

Fix part 1: relocate the tree to ai/examples/cloud-deployment (ai/ is already bundle-excluded; internal imports are bare neo.mjs/ specifiers so the move is safe) and update the cloud-deployment guide links + the two shell-script install hints.

Fix part 2: add a .claude/ worktree exclusion to the worker lazy-context webpackExclude in the Data, Canvas, Task and App workers, so build-all never scans sibling git worktrees accumulated under .claude/worktrees/ (which still carry the old examples/ layout on their own branches).

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
### @tobiu - 2026-05-31T22:35:39Z

build all webpack parts work on the repo, but checking it for worktrees is claude territory. a follow-up ticket for jsdoc issues inside the build is recommended.

### @neo-opus-ada - 2026-06-01T10:49:02Z

## Resolved — closing as completed

V-B-A: #12270's prescribed fix (relocate `examples/cloud-deployment/` under `ai/` to unbreak `build-all`) already shipped on `dev`:

- Commit `1bb665722` — `fix(build): move cloud-deployment examples to ai/ + exclude .claude from worker import globs (#12270) (#12272)` (via PR #12272).
- The tree now lives at `ai/examples/cloud-deployment/minimal-external-workspace/` (confirmed on `dev` via `git ls-tree`).
- Under `ai/`, the example is caught by the worker import-glob `webpackExclude` (`…|ai(?:\/|\\)|…`), so `src/worker/Data.mjs`'s lazy-import context no longer bundles it and the `Can't resolve 'neo.mjs/ai/services/knowledge-base/source/Base.mjs'` resolution error is gone.

The ticket was simply never closed after #12272 merged.

(For the record: the *separate* `test/`-spec worker-glob leak introduced alongside #12272 is distinct scope, tracked + fixed in #12298.)

Closing as completed.

— @neo-opus-ada (Claude Opus 4.8, 1M context). Session da9a6007.


- 2026-06-01T10:49:03Z @neo-opus-ada closed this issue

