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	14937
title	Turnkey peer onboarding runbook: one dry-run-first script chains define → repo → identity → launch → auth handoff
state	Open
labels	[]
assignees	neo-fable
createdAt	7:29 AM
updatedAt	7:29 AM
githubUrl	https://github.com/neomjs/neo/issues/14937
author	neo-fable
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]

Turnkey peer onboarding runbook: one dry-run-first script chains define → repo → identity → launch → auth handoff

Open Backlog/active-chunk-5 []

neo-fable commented on 7:29 AM

Context

The peer-onboarding rail's capstone leaf (parent #13015). Tonight's three rail PRs each ship one segment: PR #14918 (#14914 — curated per-family launch templates, isolated instance homes, minimal child env, authRequired surfacing), PR #14931 (#14915 — Day-0 resident identity: AgentIdentity node + wake route, three-key contract), PR #14916's generator (the four-surface roster ceremony PR payload). What no single entrypoint does yet: walk an operator from "I want a second gpt-family peer" to "a supervised harness process is running in its own home, wake-routable, awaiting exactly one codex login" — the v13.2 cornerstone-1 done-signal's Brain-side half ("@tobiu starts an agent from the UI, not a terminal"; this runbook is the wire-free proof of the same chain the cockpit Add-Peer flow will drive).

Filed contract-then-park: implementation is dependency-shadowed until #14918 + #14931 merge (the #14916 generator is a soft dependency — the runbook prints its invocation, doesn't call it). The contract is settled now so the leaf starts the moment the gates clear.

The Fix

ai/scripts/fleet/onboardPeer.mjs — operator-assisted, dry-run by default, --commit to execute, mirroring the sibling scripts' pure-planner idiom:

Define — FleetRegistryService.defineAgent({githubUsername, harnessType, id}) (curated intent only; the registry's launch stop-line stays untouched).
Repo — the startAgentProvisioned / deriveAgentRepoPath provisioning seam (contained per-instance checkout).
Identity — invoke the Day-0 resident-identity provisioning (resident anchor + wake route; fleet instance id as additive linkage) via its script contract.
Launch — FleetLifecycleService.start(id) through the curated template → supervised child in its isolated home.
Auth handoff — read status(id).authRequired and print the exact per-home operator login line (CODEX_HOME=<home> codex login / claude-code equivalent) — secrets never touch the script; auth is the operator-owned step by design.
Roster ceremony pointer — print the #14916 generator invocation for the four-surface roster PR.

Idempotent per segment (each underlying piece already is); a re-run reports per-segment EXISTS/CREATE and never duplicates. Dry-run renders the true per-segment delta.

Contract Ledger

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
`onboardPeer.mjs` CLI	script JSDoc + the three rail PRs' shipped contracts	dry-run default; `--commit` chains segments 1–5; per-segment idempotency report	refuse on any segment failure, nothing rolled forward	script JSDoc	unit specs on the pure planner (segment-state matrix)
auth handoff	operator-owned credential boundary	prints login line; never reads/stores/injects operator credentials	n/a (print-only)	script JSDoc	spec: output contains no secret-bearing env

Acceptance Criteria

One command, dry-run default, walks all six segments with an honest per-segment delta
--commit ends with: supervised process running, authRequired: true surfaced, login line printed
No secret is read, stored, or printed by the script; the wire-authority boundaries of the underlying services are consumed, never widened
Pure planner unit-tested; live chain = operator-assisted post-merge validation
Cross-family review

Out of Scope

The cockpit Add-Peer UI (#14807, consumes the same chain over the wire) · GitHub account creation + PAT issuance (operator-owned) · the naming ritual (post-boot) · engine-episode opening (observation-owned).

Parent: #13015 · segments: #14914 (PR #14918) · #14915 (PR #14931) · #14916 · UI sibling: #14807 · v13.2 cornerstone-1 (#14560 / #13448).

Live latest-open sweep: latest 10 open issues checked 2026-07-10T05:26Z + search "onboard peer turnkey"; no equivalent (closest: #14916 = one segment's generator, #14230 = the outcome contract this implements toward).

Origin Session ID: b956ba53-01ed-4ea6-a1e5-62969f887bc3

Retrieval Hint: query_raw_memories("turnkey peer onboarding runbook chain define repo identity launch auth handoff")