What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

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

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Frontmatter

id	11118
title	Chunk resources/content/discussions/ to bypass GitHub''s 1000-file folder cap (preventive sibling to #11113)
state	Closed
labels	enhancementaimodel-experience
assignees	neo-gemini-3-1-pro
createdAt	May 10, 2026, 4:24 PM
updatedAt	May 10, 2026, 6:47 PM
githubUrl	https://github.com/neomjs/neo/issues/11118
author	neo-opus-4-7
commentsCount	0
parentIssue	11120
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 10, 2026, 6:47 PM

to bypass GitHub's 1000-file folder cap (preventive sibling to #11113)

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closedenhancementaimodel-experience

neo-opus-4-7 commented on May 10, 2026, 4:24 PM

Context

Operator @tobiu surfaced 2026-05-10 during PR #11114 review:

"follow up tickets (where we can do better!) => we also sync discussions and pr conversations now. we do not have archives and chunking in place there yet."

resources/content/discussions/ currently holds 64 markdown files (one per synced GitHub Discussion). Distance to GitHub's 1000-file cap is large (~15× headroom; years away at current cadence). This is preventive substrate-evolution, not urgent — but worth filing alongside the more-urgent PR-side chunking (#11117) so the substrate primitive lands once across all GH-content sync types.

The Problem

When resources/content/discussions/ exceeds 1000 files, GitHub's web UI folder tree truncates display. Same friction class as #11113 (issues) and #11117 (PRs). Filing now lets the chunking land alongside the PR-side work + reuses the same substrate primitive.

Discussion-archive separation is also missing: there is no discussion-archive/ sibling to issue-archive/. As Discussions accumulate over years, the same UX-degradation friction emerges.

The Architectural Reality

ai/services/github-workflow/sync/DiscussionSyncer.mjs writes Discussion content to resources/content/discussions/discussion-NNNNN.md (flat shape). Consumers: build scripts, possibly portal app views.

Per #11113 / #11114 substrate (post-merge): inherit the chunking convention chosen by Gemini (currently XXxx per PR #11114; pending cycle-3 defense). Single substrate primitive across all GH-content syncs.

The Fix

Apply the same chunking + archive pattern that #11114 established for issues:

Subdivide resources/content/discussions/ into chunked sub-folders using whatever convention #11114 cycle-3 documents.
Create resources/content/discussion-archive/ with same chunked structure for closed Discussions (or by-Discussion-state criteria — TBD).
Update DiscussionSyncer.mjs to dynamically compute + write to the chunked path.
Update consumers for recursive readdir parsing.
Migration script to organize existing 64 files into the chunked structure.

Per #11116 friction-gold lesson: consider 2-sub-ticket split (code-side + data-migration). For this ticket the data-migration is small (64 files vs 4190 for issues), so single-PR may be acceptable — but document the decision rationale.

Acceptance Criteria

DiscussionSyncer.mjs writes new Discussions to chunked sub-folder per chosen convention
resources/content/discussion-archive/ exists with same chunked structure (if archive-separation policy is in scope here)
All consumer scripts updated for recursive readdir
Existing 64 Discussion markdown files migrated into chunked structure
Naming convention documented (inheriting from #11114 cycle-3 outcome)

Out of Scope

Naming-convention re-decision — defer to #11114 cycle-3 outcome.
PR conversation chunking — separate sibling ticket (#11117).
Generalized GH-content-chunking utility — premature; extract once 3 content types are individually chunked + the duplication friction warrants it.
Active vs archive lifecycle policy for Discussions — define separately if scope requires.
Pre-emptive cap-monitoring — could be a substrate observability ticket, but not this ticket's scope.

Avoided Traps / Gold Standards Rejected

Decision Matrix

Mirror #11113/#11114/#11117 chunking + archive pattern (Selected): Same substrate primitive applied to a 3rd content type. Single-substrate-across-types is the substrate-correct shape.
Defer until cap is actually approached: Rejected. 64 files is far from cap, but filing now lets the work batch naturally with PR-side chunking (#11117) + reduces total swarm-cycles spent on the same substrate primitive across 3 separate cycles.
Skip the discussion chunking entirely (treat as low-priority): Rejected. Operator framed it explicitly: "we do not have archives and chunking in place there yet." Filing acknowledges the gap; defer-implementation-priority is operator's call.
Combine with #11117 into a single epic: Considered. Pro: shared substrate primitive lands once. Con: discussions are 11× smaller than PRs; bundling delays the more-urgent PR-side work. Filed as siblings; can graduate to epic if #11117 implementation surfaces shared-utility extraction.

Trap: Treating preventive substrate-evolution as low-priority. Rejection: Operator's "we can do better" framing is not low-priority — it's a substrate-quality observation. Filing-now is the substrate-correct response; implementation priority can be operator-paced.

#11113 (canonical issue chunking ticket)
PR #11114 (in flight; #11113 implementation)
#11116 (sister substrate-evolution: code-vs-data-migration commit-shape discipline)
#11117 (sibling: PR conversation chunking; more urgent than this ticket; same substrate primitive)
Operator framing 2026-05-10 (this session — [paraphrase]: "we also sync discussions and pr conversations now")
Substrate-quality [RETROSPECTIVE]: Once issues + PRs + Discussions are all chunked, the GH-content-chunking primitive should be extracted to a shared utility (NOT in this ticket's scope; flag as future generalization candidate).

Origin Session ID: c2912891-b459-4a03-b2af-154d5e264df1 Retrieval Hint: "Discussion chunking", "resources/content/discussions 1k cap preventive", "DiscussionSyncer chunked path"

tobiu referenced in commit e4ab571 - "feature(github-workflow): Sync discussions into chunked directories (#11118) (#11125) on May 10, 2026, 6:47 PM

tobiu closed this issue on May 10, 2026, 6:47 PM