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	14860
title	F2 local-first gate: fresh clone reaches first persistence
state	Closed
labels	enhancementdeveloper-experienceaitesting
assignees	[]
createdAt	Jul 5, 2026, 7:55 PM
updatedAt	3:11 PM
githubUrl	https://github.com/neomjs/neo/issues/14860
author	neo-gpt
commentsCount	1
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Jul 5, 2026, 8:03 PM

F2 local-first gate: fresh clone reaches first persistence

Closed Backlog/active-chunk-4 enhancementdeveloper-experienceaitesting

neo-gpt commented on Jul 5, 2026, 7:55 PM

Context

The v13.2 ROADMAP gate still requires the local-first proof: a stranger can get from fresh clone to first persistence without hand-editing config. The prior F2 routing is no longer valid. #14672 and #14676 were closed on 2026-07-05 by operator verdict because that measurement/probe series targeted deployments we do not access and had zero relation to the local products: the agent harness, Fleet Manager, and local orchestrator.

This ticket re-cuts F2 onto the local product path under #14230. It is deliberately marked not-code-ready / needs-design because the implementation must wait for the named local surfaces to be stable enough to test honestly; the ticket exists now to prevent #14782 from pointing at closed cloud-deployment probes.

Live latest-open sweep: checked the latest 20 open issues immediately before creation on 2026-07-05; no equivalent local-F2 successor found. Exact GitHub searches for local-first F2 first persistence fresh clone hand-edited config local harness and fork running Agent OS first persistence first PR 30 minutes found #14230 as the parent and no duplicate leaf. A2A in-flight sweep: latest 30 all-status messages checked at the same boundary; no competing F2/local-first claim found.

The Problem

#14782 still needs an F2 surface, but the old answer is wrong. Measuring client/cloud deployment probes would produce a number for a product path v13.2 is not shipping as the public local-first proof. The release gate is local and falsifiable: a fresh clone reaches first durable local harness state without hand-edited config.

Without this re-cut, v13.2 can accidentally keep a dead measurement dependency alive: F1 has #14840, F3 has #14841, but F2 points at closed tickets that the operator explicitly rejected as the wrong deployment class.

The Architectural Reality

#14230 is the parent outcome contract: fork -> running Agent OS -> first claimed lane -> first PR in <= 30 minutes, with zero hand-edited config and local products only. Its 2026-07-02 sequencing comment parks full onboarding behind Fleet Manager plus self-configuring Agent OS, but it also preserves the external acceptance target v13.2 must design against.

The relevant implementation ownership zones from npm run --silent ai:structure-map -- --files --loc are:

apps/agentos for the cockpit/front-door surface.
ai/services/fleet for Fleet Manager define/start/observe services.
ai/daemons/orchestrator/control-plane for local lifecycle actuation.
ai/services/memory-core for durable local persistence evidence.
test/playwright/e2e for the eventual custom-config acceptance proof.

This ticket is not a hosted-tier probe and not a cloud deployment metric. It is a local acceptance gate over those surfaces.

The Fix

Define and later implement the local F2 acceptance path:

Start from a fresh local checkout / isolated local harness state.
Run the supported local bootstrap/start flow without hand-editing config files.
Reach a running Agent OS / Fleet Manager surface that can prove local readiness.
Produce the first durable local persistence event in Memory Core.
Emit a machine-readable gate artifact with provenance: command path, environment class, start/end timestamps, first-persistence evidence, and failure reason if blocked.
Feed #14782 F2 and the v13.2 release-note evidence line from that artifact, not from prose.

Until Fleet Manager and self-configuring Agent OS expose stable entrypoints, this ticket remains the F2 contract and dependency map rather than a branchable implementation lane.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Local F2 gate command / runner	ROADMAP.md + #14230 + #14782 F2	Executes the supported fresh-clone local path without hand-edited config and emits one JSON-first gate artifact	If a prerequisite surface is absent, report `blocked` with the missing surface; do not synthesize success	runner JSDoc + issue evidence note	custom Playwright or node-runner evidence using Neo's explicit configs, never default `npx playwright test`
No-hand-edit config invariant	ROADMAP.md release gate + #14230	The run uses template/self-config/bootstrap surfaces only; manual edits to config files fail the gate	Unsupported environment is recorded as a blocked environment class	onboarding docs / release-note evidence line	artifact lists touched config inputs and proves no manual edit step exists
First durable local persistence evidence	#14230 local-first target + Memory Core ownership	Captures the first successful local durable Memory Core write or equivalent local persistence marker	Missing persistence marker blocks F2; no timestamp guess from outer logs	Memory Core seam JSDoc when implemented	artifact cites persistence id / timestamp / local store class
Release evidence handoff	#14782 F2 + v13.2 release notes discipline	Release artifact cites the measured local gate result with provenance and failure semantics	No artifact => no F2 measured claim	v13.2 release notes / launch comment	greppable evidence line with artifact path or URL
Dependency honesty	#14230 sequencing comment	Gate stays `not-code-ready` until Fleet Manager + self-configuring Agent OS expose stable local entrypoints	If surfaces drift, update this ticket before implementation pickup	issue comment / dependency note	intake re-check proves entrypoints before branch work

Decision Record impact

none for this ticket as a contract/gate re-cut. If implementation changes lifecycle-write or read-observe authority, it must apply the relevant ADR authority at ticket-intake / PR time instead of smuggling that change into this F2 gate.

Acceptance Criteria

F2 is no longer routed through #14672 / #14676; #14782 comments or successor references point to this local-first path instead.
The final implementation uses the local agent harness / Fleet Manager / local orchestrator path, not client cloud deployment probes.
A fresh local run reaches first durable local persistence without hand-editing config files, or emits a machine-readable blocked artifact naming the missing surface.
The evidence artifact is JSON-first and includes command path, environment class, start/end timestamps, first-persistence evidence, and failure reason when applicable.
The eventual verification uses Neo's explicit custom test/runner configuration; default npx playwright test is not used as evidence.
v13.2 release notes / launch artifacts cite the F2 result with provenance rather than prose.

Out of Scope

Hosted/cloud/client deployment probes.
Pricing, packaging, or private business-repo work.
J2 operator journey work (#14840) and F3 reach metrics (#14841).
Implementing Fleet Manager or self-configuring Agent OS internals; this ticket consumes them once stable.
Generic install-doc rewrites without a measurable local gate artifact.

Avoided Traps

Do not resurrect #14672 / #14676; they were closed because they measured the wrong deployment class.
Do not claim F2 from a maintainer-prepared machine only. The artifact must expose the environment class and setup path.
Do not replace first persistence with an outer log timestamp guess.
Do not weaken the gate into prose documentation. The release claim needs a falsifiable artifact.
Do not add new cloud assumptions to the local-first public surface.

Parent: #14230. Measurement umbrella: #14782. Integration journeys: #14781. Sibling F1 leaf: #14840. Sibling F3 leaf: #14841. Roadmap anchor: v13.2 local-first Agent OS onboarding.

Origin Session ID: 6ab85930-3c14-4b18-b3b3-97989d1e75c6 Retrieval Hint: "F2 local-first gate fresh clone first persistence no hand-edited config local harness Fleet Manager self-configuring Agent OS #14230 #14782"