---
number: 9899
title: 'docs: add Core Engine Pipeline cross-references and tree.json pointers (#9898)'
author: tobiu
state: MERGED
createdAt: '2026-04-12T08:44:04Z'
updatedAt: '2026-04-12T08:53:52Z'
closedAt: '2026-04-12T08:53:49Z'
mergedAt: '2026-04-12T08:53:49Z'
head: agent/9898-core-engine-crossrefs
base: dev
url: 'https://github.com/neomjs/neo/pull/9899'
---
Resolves #9898

## Summary

Low-hanging-fruit documentation enhancement by **Antigravity (Claude Opus 4.6)** that adds navigation breadcrumbs between the high-level CodebaseOverview and the deep-dive Core Engine guides.

## Changes

### CodebaseOverview.md (2 edits)

**1. Core Engine Deep Dives block** (after Two-Tier Reactivity, ~L126):
Added a blockquote cross-reference listing all 6 core engine guides in reading order with one-line summaries of each guide's unique knowledge delta. Notes that the series forms a sequential narrative.

**2. Learning Materials section** (~L365):
- Added `learn/tree.json` as "The Index" — the canonical hierarchical taxonomy of all 130+ topics
- Expanded the topic list from 5 generic bullets to 8 precise categories with topic counts derived from the actual `tree.json` structure
- Added Agent OS & Conversational UIs, DevIndex App, Tutorials, and Engine vs Frameworks as previously missing top-level categories

### AGENTS_STARTUP.md (1 edit)

**Step 1 expansion** (~L25):
Added a "Documentation Taxonomy" paragraph directing agents to scan `learn/tree.json` alongside the CodebaseOverview. This gives agents an instant structural overview that makes subsequent knowledge base queries far more targeted.

## Rationale

The startup workflow already mandates reading `src/Neo.mjs` (1,212 lines) and `src/core/Base.mjs` (1,289 lines), which provide implementation mechanics. The 6 core engine guides provide the *architectural reasoning* — constructor trap motivation, configSymbol batch resolution proof, v10 Push/Pull integration bridge — but had zero pointers from either routing document.

`learn/tree.json` is the structural backbone consumed by `LearningSource.mjs` to build the entire Knowledge Base index, yet was absent from all agent-facing documentation.

## Scope

- Documentation-only. No code changes.
- 2 files modified, 24 insertions, 4 deletions.

## Comments

### `@tobiu` commented on 2026-04-12T08:45:20Z

**Input from Antigravity (Claude Opus 4.6):**

> ❋ # PR Review Summary
> 
> **Status:** Approved
> 
> Documentation-only PR that closes the navigation gap between the high-level CodebaseOverview and the deep-dive Core Engine guides. No code changes, no risk of regression. Clean, surgical edits.
> 
> ---
> 
> ### 📊 Evaluation Metrics
> *   **`[ARCH_ALIGNMENT]`**: 100 — Pure documentation enhancement following existing section patterns and blockquote formatting conventions already used in the document.
> *   **`[CONTENT_COMPLETENESS]`**: 100 — All 6 core engine guides are listed with accurate one-line knowledge deltas derived from actual guide content. The `tree.json` reference correctly identifies it as the Knowledge Base's structural backbone via `LearningSource.mjs`. Topic counts verified against the actual 159-line JSON structure. No JSDoc gate applies (docs-only).
> *   **`[EXECUTION_QUALITY]`**: 95 — Clean diff (24 insertions, 4 deletions). The blockquote format for the Core Engine Deep Dives section is a natural fit — visually distinct without disrupting the document's heading hierarchy. One minor observation: the "Blog" line in the Learning Materials section doesn't have a topic count like the others, but this is acceptable since blog posts aren't tracked in `tree.json`.
> *   **`[PRODUCTIVITY]`**: 100 — All three proposed changes from the expanded ticket scope are fully delivered.
> *   **`[IMPACT]`**: 70 — High leverage for agent onboarding but documentation-only. Every future agent session benefits from these breadcrumbs, making core engine concepts discoverable directly from the two primary routing documents.
> *   **`[COMPLEXITY]`**: 15 — Minimal complexity. Text-only edits to 2 files.
> *   **`[EFFORT_PROFILE]`**: Quick Win — Precisely the kind of low-hanging fruit with disproportionate impact on agent effectiveness.
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> *   **Target Issue ID:** Resolves #9898
> *   **Related Graph Nodes:** `CodebaseOverview`, `AGENTS_STARTUP`, `learn/tree.json`, `learn/guides/coreengine/*`
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> 
> *   **`[KB_GAP]`**: The analysis that prompted this PR revealed that `learn/tree.json` — despite being the canonical index consumed by `LearningSource.mjs` — had zero references in any agent-facing documentation. This gap meant agents couldn't discover the documentation taxonomy without blind `list_dir` traversals.
> *   **`[RETROSPECTIVE]`**: This PR establishes the pattern of "navigation breadcrumbs" — cross-referencing between high-level overview documents and deep-dive guide series. The same pattern could benefit other guide categories (UI Building Blocks, Data Handling, Advanced Architecture) in future iterations. The key insight: source files give agents the *mechanics*, guides give them the *reasoning*, and the overview needs explicit pointers to both.
> 
> ---
> 
> ### 📋 Required Actions
> 
> None — approved for merge.
> 
> The diff is clean, scoped, and factually accurate. Ready for squash merge.

---

