Frontmatter
| title | >- |
| docs | expand CodebaseOverview with Agent OS internals and DevIndex |
| author | tobiu |
| state | Merged |
| createdAt | Apr 12, 2026, 10:10 AM |
| updatedAt | Apr 12, 2026, 10:29 AM |
| closedAt | Apr 12, 2026, 10:29 AM |
| mergedAt | Apr 12, 2026, 10:29 AM |
| branches | dev ← agent/9892-codebase-overview-internals |
| url | https://github.com/neomjs/neo/pull/9897 |
Merged
tobiu
commented on Apr 12, 2026, 10:25 AM
Input from Claude Opus 4.6 (Antigravity):
❋ ## Post-Push Delta (Review Feedback)
Addressed two corrections from review:
1. Flagship App Reordering
- DevIndex promoted to #2 (after Portal) — architecturally significant as the only backend-runtime Neo app
- SharedCovid moved to #3
- RealWorld demoted to #4 with honest context: Conduit's rigid DOM template requirements constrain Neo to
component.Base, making it an anti-pattern for the component library. API patterns remain useful.2. Neural Link Three-Tier Introspection (replaced shallow description)
The original "feeding structured JSON component blueprints" was less accurate than the old version. Replaced with:
- Component Trees: JSON-like but richer — class instances with full config state,
toJSON()exports- VDOM: Pure JSON desired next state (pending
update()). Syntax:tag,cls,cn- VNode: Pure JSON current live DOM state. Syntax:
nodeName,className,childNodes— deliberately different to distinguish at a glance- Delta pipeline:
TreeBuilder.mjs→ symmetric VDOM/VNode trees withupdateDepth→ VDom Worker →Helper.mjsconverts VDOM→VNode → compares two VNode trees → minimal delta stream (loggable in main for debugging)- VDOM Teleportation: Components flagged for updates carry their own
updateDepth, allowing parents to send only dirty children to the VDom Worker
tobiu
commented on Apr 12, 2026, 10:28 AM
Input from Claude Opus 4.6 (Antigravity):
❋ # PR Review Summary
Status: Approved
This PR delivers on all 6 content areas specified in #9892 and incorporates two substantial post-push corrections (app reordering, three-tier introspection) that significantly improved accuracy.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 95 - All new content is grounded in source file analysis (7 files read). The three-tier introspection explanation (Component Trees / VDOM / VNode) accurately reflects the framework's actual rendering pipeline. The VDOM Teleportation concept andupdateDepthmechanics are correctly described relative toTreeBuilder.mjsandHelper.mjs.[CONTENT_COMPLETENESS]: 98 - All 6 ticket requirements fulfilled. The post-push delta comment properly documents the RealWorld anti-pattern context and the Neural Link correction. The only gap: theask_knowledge_basescope extension from the ticket comment was already addressed in #9893/#9894, which could have been noted explicitly.[EXECUTION_QUALITY]: 95 - Single file modified, clean diff (49 insertions, 9 deletions). Heading hierarchy (##→###→####) is consistent. No duplication with #9875 (scale metrics) or #9893 (tooling references). ASCII diagram for Bridge topology is clear and renders correctly.[PRODUCTIVITY]: 100 - All 6 goals from the ticket are fully addressed: DevIndex flagship entry, Bridge topology diagram, daemon lifecycle scripts, ToolService documentation, agent profiles, ConnectionService session awareness.[IMPACT]: 75 - Documentation-only change targeting agent onboarding quality. High value for reducing new-agent ramp-up time and preventing hallucinations about Agent OS internals. Does not affect runtime behavior.[COMPLEXITY]: 30 - Single markdown file with well-scoped insertions. No code changes, no cross-file dependencies. Complexity is in the accuracy of content, not structural risk.[EFFORT_PROFILE]: Quick Win - High documentation ROI for moderate research effort. The source file analysis (7 files) provides durable accuracy.
🕸️ Context & Graph Linking
- Target Issue: Resolves #9892
- Related Graph Nodes:
CodebaseOverview.md,CONCEPT:DevIndex,CONCEPT:NeuralLink,CONCEPT:BridgeTopology,CLASS:ToolService,CLASS:ConnectionService,CLASS:DreamService,FILE:TreeBuilder.mjs,FILE:Helper.mjs- Prior PRs: #9894 (ask_knowledge_base promotion), #9896 (PullRequestService CWD fix)
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: The three-tier introspection model (Component Trees / VDOM / VNode) is a critical architectural differentiator that was previously under-documented. The distinction between VDOM syntax (tag,cls,cn) and VNode syntax (nodeName,className,childNodes) is a deliberate design choice for disambiguation — this should be reinforced in future agent training contexts. The RealWorld anti-pattern callout is architecturally honest and prevents agents from using it as a reference implementation.[RETROSPECTIVE]: VDOM Teleportation (flagged components carrying their ownupdateDepthto skip clean siblings during diff) is a performance optimization that agents must understand when debugging "too many deltas" — this is now documented in the canonical onboarding guide.
📋 Required Actions
No blocking items. PR is approved for merge.
- All 6 ticket requirements addressed
- Post-push corrections incorporated (app reordering, three-tier introspection)
- No content duplication with existing sections
- Heading hierarchy consistent
Resolves #9892
Summary
Expands
CodebaseOverview.mdwith 6 missing content areas identified during deep-read sessions:Changes Made
Neo.core.Baseworks as a Node.js backend runtime. Documents Spider (6 discovery strategies), Updater (meritocracy logic), Storage (flat-file persistence).node buildScripts/ai/runSandman.mjs,runGoldenPath.mjs) + maintenance utilities. Clarifies these are Node.js scripts, not MCP operations.ai/mcp/ToolService.mjsas the universal dispatch layer —callTool()as the single choke-point for all 5 MCP servers with OpenAPI-driven Zod validation.Scope Boundary
Documentation-only. No code changes. No overlap with #9875 (which addressed scale metrics) or #9893 (which addressed
ask_knowledge_basetooling references).Verification
##→###→####nesting)