What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	15767
title	Cloud guides: project-identity migration callout + state-hash recipe
state	Closed
labels	documentationenhancementai
assignees	neo-gpt-emmy
createdAt	Jul 23, 2026, 9:48 PM
updatedAt	Jul 23, 2026, 11:01 PM
githubUrl	https://github.com/neomjs/neo/issues/15767
author	neo-opus-vega
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Jul 23, 2026, 11:01 PM

Cloud guides: project-identity migration callout + state-hash recipe

Closed Backlog/active-chunk-9 documentationenhancementai

neo-opus-vega commented on Jul 23, 2026, 9:48 PM

Context

PR #15764 (merged 2026-07-23T19:17Z) added the orchestrator-state named volume and a Day-0 handoff checklist step that tells operators to "record hashes for orchestrator-state.json and tenant-repo-sync-revisions.json before redeploy". PR #15765 (merged 2026-07-23T19:46Z) added the top-level name: "${NEO_DEPLOY_PROJECT_NAME:-neo-agent-os}" project identity to the canonical compose. Both reviews (4767388001, 4767442988) flagged the same two operator-facing documentation gaps as calibrated non-blocking findings; this ticket converts those watch-items into tracked substrate. Priority context: cloud-deployment stability is the current prio-zero goal (operator directive 2026-07-23).

The Problem

Migration hazard for pre-existing deployments. Before PR #15765, a deployment started with bare docker compose up (no -p, no COMPOSE_PROJECT_NAME, no env) resolved the compose-dir basename deploy as its Compose project — the old PipelineWiring rule 2 documented exactly that default. After upgrading to the post-#15765 compose, the same bare command resolves project neo-agent-os instead: Docker creates fresh, empty named volumes, and the old deploy_* volumes (including the Memory Core primary store) remain on disk but unreferenced. The updated failure-signature row covers recovery, but nothing warns the operator before the first post-upgrade up.
The hash step has no how. The Day-0 checklist instructs recording state-file hashes with no concrete command; the Milestone 7a integration witness embodies one, but operators do not read spec files.

The Architectural Reality

Compose precedence: the top-level name: yields to -p / COMPOSE_PROJECT_NAME / the env interpolation — so NEO_DEPLOY_PROJECT_NAME=deploy is a valid, zero-migration keep-my-volumes path for affected deployments.
Reference-script deployments are UNAFFECTED: ai/examples/cloud-deployment/deploy-pipeline.sh pinned neo-agent-os before and after, and now exports the same variable.
Affected docs: learn/agentos/cloud-deployment/PipelineWiring.md (rule 2), learn/agentos/cloud-deployment/Day0Tutorial.md (handoff checklist), optionally the learn/agentos/DeploymentCookbook.md identity paragraph.

The Fix

Add a migration callout to PipelineWiring rule 2 (and/or the cookbook identity paragraph): deployments that previously ran without an explicit project name were on project deploy; set NEO_DEPLOY_PROJECT_NAME=deploy before the first post-upgrade command — or deliberately migrate volume data — otherwise the stack starts on fresh empty volumes.
Give the Day-0 hash step one concrete, validated in-container command, e.g. docker compose exec orchestrator sh -c 'sha256sum "$NEO_AI_ORCHESTRATOR_DIR"/orchestrator-state.json "$NEO_AI_ORCHESTRATOR_DIR"/tenant-repo-sync-revisions.json' (validate the exact form against the image's shell tooling before documenting).

Acceptance Criteria

PipelineWiring rule 2 (or the cookbook identity paragraph) carries the pre-upgrade migration callout naming the legacy deploy project and the NEO_DEPLOY_PROJECT_NAME=deploy escape hatch.
The Day-0 handoff checklist's hash step names one concrete command, validated against the shipped image.
npm run ai:lint-guides reports 0 hard findings on the touched guides.

Out of Scope

Any compose or code change; automated volume-migration tooling; the off-host backup/export policy (deliberately an operational preference per the PR #15764 review calibration).

#15759 / PR #15764 (state volume + checklist step), #15762 / PR #15765 (project identity), review anchors 4767388001 + 4767442988.

Decision Record impact: none — documents shipped #15764/#15765 behavior.

Release classification: not release-blocking (docs polish; boardless).

Live latest-open sweep: checked latest 20 open issues at 2026-07-23T19:47:02Z; no equivalent found. A2A claim sweep (all-status, last 30): no overlapping [lane-claim]/[lane-intent].

Origin Session ID: 9af3c9a5-efc2-4716-bb5c-19289e22ddcc

Retrieval Hint: NEO_DEPLOY_PROJECT_NAME migration callout legacy deploy project fresh empty volumes