@reicek/neataptic-ts 0.1.25 → 0.1.26

package/.github/copilot-instructions.md

@@ -91,6 +91,15 @@ When a generated `src/**/README.md` appears outdated relative to the code or JSD
 - run `npm run docs` to refresh generated documentation when needed,
 - consider `educational-docs` pre-approved to run `npm run docs` after doc-affecting edits so README files stay synchronized and drift does not confuse later work.
 
+CI-sensitive docs and tooling validation
+---------------------------------------
+When a task touches `.github/workflows/**`, `package.json`, `package-lock.json`, `scripts/**` that launch docs or browser tooling, Mermaid rendering, Puppeteer/Chromium, or any dependency change that can affect those paths:
+
+- do not treat local Windows success as sufficient evidence for GitHub-hosted Linux runners,
+- run `npm ci` after manifest or lockfile edits and report pass/fail before claiming the workflow is fixed,
+- run `npm run docs` when Mermaid, Puppeteer, docs generation, or related launch scripts are affected,
+- when browser-based docs tooling runs in Linux CI, explicitly account for Chromium sandbox restrictions and prefer durable script-level launch configuration over workflow-only ad hoc flags.
+
 Folder README reconnaissance (read this before deep code search)
 ---------------------------------------------------------------
 Because JSDoc is auto-compiled into each folder's `README.md`, those README files are the fastest condensed overview of a module's purpose, exported surface, neighboring files, and intended usage.
@@ -327,8 +336,10 @@ When you modify or create files under `src/` or `test/`, run (or advise running)
    Quick checks to run (recommended)
    --------------------------------
    - TypeScript: run `npm run build` and report pass/fail.
+   - Clean install: when `package.json`, `package-lock.json`, or workflow/runtime tooling changes, run `npm ci` and report pass/fail.
    - Tests heuristic: flag test files that contain more than one `expect(` occurrence (these should be split into multiple `it()` blocks).
    - JSDoc: for new exported symbols, ensure a JSDoc block with `@param`/`@returns` exists (or flag if missing).
+   - CI browser/docs tooling: when the changed path can invoke Mermaid, Puppeteer, or Chromium in CI, validate `npm run docs` and do not assume local non-Linux success generalizes to GitHub-hosted Linux.
    - ES2023 modernization: flag legacy patterns and suggest modern equivalents (see below one-liners).
 
    PowerShell examples (local validation)

package/.github/skills/trace-analyzer-extension/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trace-analyzer-extension
-description: 'Extend scripts/analyze-trace.ts with new rollups, comparisons, script attribution, percentiles, or deterministic report sections. Use when the existing trace analyzer cannot answer an engineering question about Chrome trace or Perfetto data.'
+description: 'Extend scripts/analyze-trace/analyze-trace.ts with new rollups, comparisons, script attribution, percentiles, or deterministic report sections. Use when the existing trace analyzer cannot answer an engineering question about Chrome trace or Perfetto data.'
 argument-hint: 'Describe the trace question, missing metric, and validation trace file.'
 user-invocable: true
 disable-model-invocation: false
@@ -8,7 +8,7 @@ disable-model-invocation: false
 
 # Trace Analyzer Extension
 
-Use this skill when an agent needs to modify `scripts/analyze-trace.ts` instead
+Use this skill when an agent needs to modify `scripts/analyze-trace/analyze-trace.ts` instead
 of only consuming its current output.
 
 ## When to Use
@@ -27,7 +27,7 @@ of only consuming its current output.
 ## Standard Workflow
 
 1. State the engineering question the current analyzer cannot answer.
-2. Read `scripts/analyze-trace.ts` before proposing a new section.
+2. Read `scripts/analyze-trace/analyze-trace.ts` before proposing a new section.
 3. Prefer extending existing helpers over adding parallel ad hoc logic.
 4. Keep output deterministic, text-first, and easy to compare across captures.
 5. Validate the new output against a real trace file from the repo.

package/.github/skills/trace-analyzer-extension/assets/extension-checklist.md

@@ -1,6 +1,6 @@
 # Trace Analyzer Extension Checklist
 
-Use this checklist before finalizing changes to `scripts/analyze-trace.ts`.
+Use this checklist before finalizing changes to `scripts/analyze-trace/analyze-trace.ts`.
 
 ## Before Editing
 

package/.github/skills/trace-analyzer-extension/references/analyzer-extension-workflow.md

@@ -1,6 +1,6 @@
 # Analyzer Extension Workflow
 
-This reference explains how to safely extend `scripts/analyze-trace.ts` without
+This reference explains how to safely extend `scripts/analyze-trace/analyze-trace.ts` without
 turning it into a one-off debugging script.
 
 ## Start With the Question

package/.github/skills/trace-audit-reporting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trace-audit-reporting
-description: 'Analyze Chrome trace or Perfetto trace captures, run scripts/analyze-trace.ts, map hotspots to NeatapticTS source files, and generate a detailed performance report with findings, evidence, and an action plan. Use when auditing renderer, worker, GPU, requestAnimationFrame, postMessage, or long-task regressions.'
+description: 'Analyze Chrome trace or Perfetto trace captures, run scripts/analyze-trace/analyze-trace.ts, map hotspots to NeatapticTS source files, and generate a detailed performance report with findings, evidence, and an action plan. Use when auditing renderer, worker, GPU, requestAnimationFrame, postMessage, or long-task regressions.'
 argument-hint: 'Describe the trace file, feature area, and target report file.'
 user-invocable: true
 disable-model-invocation: false
@@ -42,7 +42,7 @@ surface for the library rather than the final destination for a workaround.
 - [Trace analysis workflow](./references/trace-analysis-workflow.md)
 - [Performance report template](./assets/performance-report-template.md)
 - Companion skill: `trace-analyzer-extension` for modifying
-  `scripts/analyze-trace.ts` itself when new rollups or comparisons are needed.
+  `scripts/analyze-trace/analyze-trace.ts` itself when new rollups or comparisons are needed.
 
 ## Standard Workflow
 
@@ -97,7 +97,7 @@ surface for the library rather than the final destination for a workaround.
 
 ## Repo-Specific Notes
 
-- This repository already includes `scripts/analyze-trace.ts` for compact,
+- This repository already includes `scripts/analyze-trace/analyze-trace.ts` for compact,
   thread-aware trace audits.
 - For work in `src/` or `test/`, consult the nearest folder `README.md` before
   deep file reads.

package/.github/skills/trace-audit-reporting/references/trace-analysis-workflow.md

@@ -116,7 +116,7 @@ Use these heuristics when the trace touches evaluation or inference paths:
 
 ## When to Extend the Analyzer
 
-Modify `scripts/analyze-trace.ts` only when the existing output cannot answer a
+Modify `scripts/analyze-trace/analyze-trace.ts` only when the existing output cannot answer a
 meaningful engineering question.
 
 Good reasons to extend it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reicek/neataptic-ts",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Architecture-free neural network library with genetic algorithm implementations",
   "main": "./dist/neataptic.js",
   "module": "./dist/neataptic.js",
@@ -12,6 +12,7 @@
     "pretest": "npm run build",
     "test:bench": "npm run jest:base -- --no-cache --runInBand --verbose --testPathPatterns=benchmark",
     "bench:asciiMaze": "node -r ts-node/register test/benchmarks/asciiMaze.micro.bench.ts",
+    "bench:tables": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-bench-tables.js",
     "test:silent": "npm run jest:base -- --no-cache --coverage --collect-coverage --runInBand --testPathIgnorePatterns=.e2e.test.ts --testPathIgnorePatterns=benchmark\\..*\\.test\\.ts$ --silent",
     "deploy": "npm run build && npm run test:dist && npm publish",
     "build": "npm run build:webpack && npm run build:ts",
@@ -20,28 +21,33 @@
     "build:ascii-maze": "npx esbuild test/examples/asciiMaze/browser-entry.ts --bundle --outfile=docs/assets/ascii-maze.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
     "build:flappy-worker": "npx esbuild test/examples/flappy_bird/flappyEvolution.worker.ts --bundle --outfile=docs/assets/flappy-evolution.worker.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
     "build:flappy-bird": "npx esbuild test/examples/flappy_bird/browser-entry/browser-entry.ts --bundle --outfile=docs/assets/flappy-bird.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
-    "trace:analyze": "npx ts-node scripts/analyze-trace.ts",
+    "trace:analyze": "npm run docs:build-scripts && node ./dist-docs/scripts/analyze-trace/analyze-trace.js",
     "start:local-server": "npx http-server . -p 8080 -c-1",
     "start:ts": "ts-node src/neataptic.ts",
     "test:e2e": "cross-env FORCE_COLOR=true NODE_OPTIONS=--no-experimental-webstorage jest e2e.test.ts --config=jest.config.mjs --no-cache --runInBand",
     "test:e2e:logs": "npm run jest:base -- e2e.test.ts --verbose --runInBand --no-cache",
     "test:dist": "npm run build:ts && npm run jest:base -- --no-cache --coverage --collect-coverage --runInBand --testPathIgnorePatterns=.e2e.test.ts --testPathIgnorePatterns=benchmark\\..*\\.test\\.ts$",
-    "docs:build-scripts": "tsc -p tsconfig.docs.json && node scripts/write-dist-docs-pkg.mjs",
-    "docs:folders:src": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js --target=src",
-    "docs:folders:asciiMaze": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js --target=asciiMaze",
-    "docs:folders:flappy-bird": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js --target=flappy-bird",
-    "docs:folders": "npm run docs:folders:src && npm run docs:folders:asciiMaze && npm run docs:folders:flappy-bird",
-    "docs:html": "npm run docs:build-scripts && node ./dist-docs/scripts/render-docs-html.js",
-    "docs:mermaid:validate": "node ./scripts/mermaid-cli.mjs validate",
-    "docs:mermaid:export": "node ./scripts/mermaid-cli.mjs export",
-    "docs:examples": "node scripts/copy-examples.mjs",
+    "docs:build-scripts": "tsc -p tsconfig.docs.json && node ./dist-docs/scripts/write-dist-docs-pkg.js",
+    "docs:folders:src:built": "node ./dist-docs/scripts/generate-docs/generate-docs.js --target=src",
+    "docs:folders:src": "npm run docs:build-scripts && npm run docs:folders:src:built",
+    "docs:folders:asciiMaze:built": "node ./dist-docs/scripts/generate-docs/generate-docs.js --target=asciiMaze",
+    "docs:folders:asciiMaze": "npm run docs:build-scripts && npm run docs:folders:asciiMaze:built",
+    "docs:folders:flappy-bird:built": "node ./dist-docs/scripts/generate-docs/generate-docs.js --target=flappy-bird",
+    "docs:folders:flappy-bird": "npm run docs:build-scripts && npm run docs:folders:flappy-bird:built",
+    "docs:folders": "npm run docs:build-scripts && node ./dist-docs/scripts/run-docs.js folders",
+    "docs:html:built": "node ./dist-docs/scripts/render-docs-html.js",
+    "docs:html": "npm run docs:build-scripts && npm run docs:html:built",
+    "docs:mermaid:validate": "npm run docs:build-scripts && node ./dist-docs/scripts/mermaid-cli.js validate",
+    "docs:mermaid:export": "npm run docs:build-scripts && node ./dist-docs/scripts/mermaid-cli.js export",
+    "docs:examples:built": "node ./dist-docs/scripts/copy-examples.js",
+    "docs:examples": "npm run docs:build-scripts && npm run docs:examples:built",
     "prettier": "npm run prettier:tests && npm run prettier:src",
     "prettier:tests": "npx prettier --write test/**/*.ts",
     "prettier:src": "npx prettier --write src/**/*.ts",
-    "docs": "npm run build:ascii-maze && npm run build:flappy-worker && npm run build:flappy-bird && npm run docs:examples && npm run docs:folders && node ./dist-docs/scripts/render-docs-html.js",
+    "docs": "npm run docs:build-scripts && node ./dist-docs/scripts/run-docs.js all",
     "lint": "eslint src/ test/",
     "lint:fix": "eslint src/ --fix",
-    "onnx:export": "node scripts/export-onnx.mjs"
+    "onnx:export": "npm run docs:build-scripts && node ./dist-docs/scripts/export-onnx.js"
   },
   "exports": {
     ".": {

package/plans/Flappy_Bird_Folder_Documentation_Pass.md

@@ -37,13 +37,13 @@ tour of the example architecture rather than a sparse export inventory.
 ## Steps
 
 - [x] Step 1: Tidy the root `test/examples/flappy_bird` surface and verify the
-  README inventory-driven workflow.
+      README inventory-driven workflow.
 - [x] Step 2: Tidy the worker and trainer-facing folders.
 - [x] Step 3: Tidy shared simulation, environment, constants, and evaluation
-  folders.
+      folders.
 - [x] Step 4: Tidy browser-entry and its nested README-owning folders one by one.
 - [x] Step 5: Regenerate docs, run focused validation, and record any durable
-  boundary notes that changed during the pass.
+      boundary notes that changed during the pass.
 
 ## Step 1 Inventory
 
@@ -114,4 +114,4 @@ tour of the example architecture rather than a sparse export inventory.
 - The todo list reflects completion folder by folder.
 - Docs regeneration succeeds after documentation-affecting changes.
 - A later session can resume from this plan and the todo list without prior chat
-  history.
+  history.

package/plans/README.md

@@ -25,34 +25,57 @@ Recommended reading order:
 
 Selection guide:
 
+- `plans/analyze-trace-solid-split.plans.md`: completed trace-analyzer tooling split and reopen point for future script-boundary work.
+- `plans/architecture-solid-split.plans.md`: active architecture folderization and boundary-ownership cleanup across `src/architecture`.
 - `plans/neat.plans.md`: core NEAT correctness, innovation tracking, crossover alignment, speciation invariants.
 - `plans/Roadmap.md`: dependency-aware execution order across all initiatives.
 - `plans/Architecture_Primitives_Node_Group_Layer.md`: first-class architecture-building primitives such as nodes, groups, and layers.
+- `plans/asciiMaze-typescript-repair.plans.md`: completed `asciiMaze` TypeScript repair baseline and reopen point for future diagnostics.
 - `plans/Browser_Build_and_CDN_Distribution.md`: browser packaging, CDN usage, and distribution ergonomics.
 - `plans/Construct_From_Parts_Graph_Assembly.md`: deterministic graph assembly and validated network construction from parts.
+- `plans/ES2023 migration`: repository-wide ES2023 syntax and modernization lane.
 - `plans/Evolution_Training_Interoperability_Contracts.md`: contracts between evolution workflows and gradient-based training.
+- `plans/Flappy_Bird_Folder_Documentation_Pass.md`: completed Flappy Bird folder documentation baseline and reopen point for example-docs follow-up.
+- `plans/generate-docs-solid-split.plans.md`: completed docs-generator tooling split and reopen point for future `scripts/generate-docs/` work.
 - `plans/HyperEvoDevoMorphoNEAT.md`: evo-devo and morphology-oriented research direction.
 - `plans/Interactive_Examples_and_Learning_Path.md`: runnable examples, onboarding flow, and learning-path improvements.
 - `plans/Memory_Optimization.md`: scaling, memory layout, and strategies for very large networks.
+- `plans/methods-docs.plans.md`: completed educational-docs lane for `src/methods` and reopen point for methods documentation drift.
+- `plans/methods-solid-split.plans.md`: completed structural split lane for `src/methods` and reopen point for later refactors.
+- `plans/neat-docs.plans.md`: active educational-docs lane for NEAT surfaces and generated README quality.
+- `plans/neat-test-surface-repair.plans.md`: completed NEAT public test-surface repair baseline and reopen point for future compatibility regressions.
 - `plans/Network_Visualization_Export_Schema.md`: stable export schema for visualization and inspection tooling.
 - `plans/ONNX_EXPORT_PLAN.md`: ONNX export/import architecture and rollout phases.
 - `plans/Population_Save_Resume_and_Checkpointing.md`: checkpointing, persistence, save/resume workflows.
 - `plans/Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md`: prebuilt architecture constructors and sequence-oriented builders.
+- `plans/render-docs-html-solid-split.plans.md`: completed HTML docs renderer split and reopen point for future docs-site tooling work.
 - `plans/src-no-explicit-any-cleanup.plans.md`: completed `src/` strict-typing cleanup baseline for `@typescript-eslint/no-explicit-any`, kept as the reopen point if later refactors reintroduce debt.
 - `plans/Stable_Activation_Ordering_and_Explicit_IO_Roles.md`: deterministic execution ordering and explicit input/output roles.
 - `plans/Standalone_Inference_Export.md`: dependency-free exported inference runtime.
 - `plans/Turnkey_Multithread_Evaluation_API.md`: parallel evaluation API for Node and browser workers.
+- `plans/utils-docs.plans.md`: completed educational-docs lane for `src/utils` and reopen point for later documentation drift.
 - `plans/Worker_Friendly_Network_Serialization_Fastpath.md`: fast serialization path for worker-based evaluation.
 
 Task-to-plan trigger phrases:
 
+- trace analyzer, Chrome trace, Perfetto report script, `trace:analyze`, tooling split reopen: `plans/analyze-trace-solid-split.plans.md`
+- architecture split, folderization, orchestration-first cleanup in `src/architecture`: `plans/architecture-solid-split.plans.md`
 - NEAT correctness, innovation IDs, crossover, compatibility distance, speciation: `plans/neat.plans.md`
 - roadmap, sequence, dependency order, what comes first: `plans/Roadmap.md`
 - architecture builder, layer API, node/group primitives: `plans/Architecture_Primitives_Node_Group_Layer.md`
+- asciiMaze TypeScript diagnostics, example test compile failures, reopen asciiMaze repair: `plans/asciiMaze-typescript-repair.plans.md`
 - construct from parts, graph assembly, deterministic builder: `plans/Construct_From_Parts_Graph_Assembly.md`
 - browser bundle, CDN, browser-first usage: `plans/Browser_Build_and_CDN_Distribution.md`
+- ES2023, immutable array methods, modernization pass, syntax cleanup, migration sequencing: `plans/ES2023 migration`
+- Flappy Bird docs pass, example folder documentation, generated README quality for Flappy: `plans/Flappy_Bird_Folder_Documentation_Pass.md`
+- generate-docs, folder README generation, docs.order, docs generator split: `plans/generate-docs-solid-split.plans.md`
 - ONNX, import/export interoperability: `plans/ONNX_EXPORT_PLAN.md`
+- methods docs, methods README quality, educational-docs for methods: `plans/methods-docs.plans.md`
+- methods split, `src/methods` refactor, methods folderization: `plans/methods-solid-split.plans.md`
+- NEAT docs, generated README quality, NEAT documentation lane: `plans/neat-docs.plans.md`
+- NEAT test surface, public type compatibility, root facade repair: `plans/neat-test-surface-repair.plans.md`
 - explicit any, no-explicit-any, strict typing, src lint cleanup follow-up, reopen completed cleanup lane: `plans/src-no-explicit-any-cleanup.plans.md`
+- HTML docs renderer, sidebar, Mermaid validation, docs site tooling split: `plans/render-docs-html-solid-split.plans.md`
 - visualization, schema, inspect network shape: `plans/Network_Visualization_Export_Schema.md`
 - checkpoint, resume, save population: `plans/Population_Save_Resume_and_Checkpointing.md`
 - workers, threads, parallel evaluation: `plans/Turnkey_Multithread_Evaluation_API.md`
@@ -64,6 +87,7 @@ Task-to-plan trigger phrases:
 - preconfigured models, MLP, LSTM, GRU, NARX builders: `plans/Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md`
 - examples, tutorials, learning path, onboarding: `plans/Interactive_Examples_and_Learning_Path.md`
 - evo-devo, morphology, research-heavy extensions: `plans/HyperEvoDevoMorphoNEAT.md`
+- utils docs, utility README quality, educational-docs for `src/utils`: `plans/utils-docs.plans.md`
 
 Working rule:
 When a task changes code in a way that could conflict with one of these plans, mention the relevant plan in the working notes or final summary and call out any mismatch instead of silently diverging from the roadmap.

package/plans/Roadmap.md

@@ -20,20 +20,27 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 - `flappy_bird` reference demo split and documentation baseline [DONE]
 - Main app NEAT surface is already SOLID split [DONE]
 - Educational documentation and split follow-through lane [WIP]
-   - [Flappy_Bird_Folder_Documentation_Pass.md](Flappy_Bird_Folder_Documentation_Pass.md) [DONE]
-   - [architecture-solid-split.plans.md](architecture-solid-split.plans.md) [WIP]
-   - [methods-solid-split.plans.md](methods-solid-split.plans.md) [DONE]
-   - [methods-docs.plans.md](methods-docs.plans.md) [DONE]
-   - [neat-docs.plans.md](neat-docs.plans.md) [WIP]
-   - [utils-docs.plans.md](utils-docs.plans.md) [DONE]
-   - Both demos are now solid split and the Flappy Bird documentation pass is complete enough to stop being a documentation blocker.
-   - The remaining structural polish in Phase 0 is the broader educational-docs lane outside methods, the architecture folderization pass, and the repository-wide modernization pass with their validation gate.
+  - [Flappy_Bird_Folder_Documentation_Pass.md](Flappy_Bird_Folder_Documentation_Pass.md) [DONE]
+  - [architecture-solid-split.plans.md](architecture-solid-split.plans.md) [WIP]
+  - [methods-solid-split.plans.md](methods-solid-split.plans.md) [DONE]
+  - [methods-docs.plans.md](methods-docs.plans.md) [DONE]
+  - [neat-docs.plans.md](neat-docs.plans.md) [WIP]
+  - [utils-docs.plans.md](utils-docs.plans.md) [DONE]
+  - Both demos are now solid split and the Flappy Bird documentation pass is complete enough to stop being a documentation blocker.
+  - The remaining structural polish in Phase 0 is the broader educational-docs lane outside methods, the architecture folderization pass, and the repository-wide modernization pass with their validation gate.
+- Supporting repair and docs-tooling stabilization lane [DONE]
+  - [neat-test-surface-repair.plans.md](neat-test-surface-repair.plans.md) [DONE]
+  - [asciiMaze-typescript-repair.plans.md](asciiMaze-typescript-repair.plans.md) [DONE]
+  - [generate-docs-solid-split.plans.md](generate-docs-solid-split.plans.md) [DONE]
+  - [render-docs-html-solid-split.plans.md](render-docs-html-solid-split.plans.md) [DONE]
+  - [analyze-trace-solid-split.plans.md](analyze-trace-solid-split.plans.md) [DONE]
+  - These remain roadmap-visible as reopen points and tooling baselines even though they do not change the forward critical path out of Phase 0.
 - Source strict-typing cleanup for `src/` explicit-`any` debt [DONE]
-   - Plan: [src-no-explicit-any-cleanup.plans.md](src-no-explicit-any-cleanup.plans.md)
-   - Scope note: this lane replaced the stale root checklist with a roadmap-tracked plan aligned to the current folderized tree and is now the closed baseline for future reopen-only follow-up.
+  - Plan: [src-no-explicit-any-cleanup.plans.md](src-no-explicit-any-cleanup.plans.md)
+  - Scope note: this lane replaced the stale root checklist with a roadmap-tracked plan aligned to the current folderized tree and is now the closed baseline for future reopen-only follow-up.
 - ES2023 modernization (after the demo-structure pass; mechanical refactors + CI enforcement) [PLANNED]
-   - Plan: [ES2023 migration](ES2023%20migration)
-   - Scope note: this phase is syntax/module modernization plus CI enforcement. Memory-management or performance-feature work remains owned by [Memory_Optimization.md](Memory_Optimization.md).
+  - Plan: [ES2023 migration](ES2023%20migration)
+  - Scope note: this phase is syntax/module modernization plus CI enforcement. Memory-management or performance-feature work remains owned by [Memory_Optimization.md](Memory_Optimization.md).
 
 **Gate to Phase 1:** both demos are solid split and documented, the main app split is stable, the remaining documentation work is no longer obscuring ownership boundaries, and `npx tsc --noEmit -p tsconfig.json` plus `npm test` are green after the modernization pass.
 
@@ -91,13 +98,20 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 9. Standalone inference export (dependency-free runtime output)
    - Plan: [Standalone_Inference_Export.md](Standalone_Inference_Export.md) [PLANNED]
 10. Worker-friendly serialization fastpath (clone/transfer payloads; predictor creation)
-   - Plan: [Worker_Friendly_Network_Serialization_Fastpath.md](Worker_Friendly_Network_Serialization_Fastpath.md) [PLANNED]
+
+- Plan: [Worker_Friendly_Network_Serialization_Fastpath.md](Worker_Friendly_Network_Serialization_Fastpath.md) [PLANNED]
+
 11. Turnkey multithread evaluation API (Node + browser workers)
-   - Plan: [Turnkey_Multithread_Evaluation_API.md](Turnkey_Multithread_Evaluation_API.md) [PLANNED]
+
+- Plan: [Turnkey_Multithread_Evaluation_API.md](Turnkey_Multithread_Evaluation_API.md) [PLANNED]
+
 12. Population save/resume + checkpointing (full vs light checkpoints, determinism contracts)
-   - Plan: [Population_Save_Resume_and_Checkpointing.md](Population_Save_Resume_and_Checkpointing.md) [PLANNED]
+
+- Plan: [Population_Save_Resume_and_Checkpointing.md](Population_Save_Resume_and_Checkpointing.md) [PLANNED]
+
 13. Evolution–training interoperability contracts (parameter vectors, isolation, hybrid policies)
-   - Plan: [Evolution_Training_Interoperability_Contracts.md](Evolution_Training_Interoperability_Contracts.md) [PLANNED]
+
+- Plan: [Evolution_Training_Interoperability_Contracts.md](Evolution_Training_Interoperability_Contracts.md) [PLANNED]
 
 **Why this ordering:**
 
@@ -113,8 +127,8 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 This plan is large and can run as a **parallel lane** after Phase 1, but it should not destabilize correctness work.
 
 - Memory & performance multi-layer strategy (Track 1: Phases 0–10; Track 2 gates Hyper work)
-   - Plan: [Memory_Optimization.md](Memory_Optimization.md) [WIP]
-   - Current internal state: Phases 0-3 are done, Phase 4 is next, and Track 2 Hyper work remains gated behind Track 1 stability.
+  - Plan: [Memory_Optimization.md](Memory_Optimization.md) [WIP]
+  - Current internal state: Phases 0-3 are done, Phase 4 is next, and Track 2 Hyper work remains gated behind Track 1 stability.
 
 **Recommended sequencing guidance:**
 
@@ -129,8 +143,8 @@ This plan is large and can run as a **parallel lane** after Phase 1, but it shou
 **Outcome:** broader ecosystem compatibility and model portability.
 
 - ONNX export/import breadth and hardening
-   - Plan: [ONNX_EXPORT_PLAN.md](ONNX_EXPORT_PLAN.md) [WIP]
-   - Current internal state: Phase 0-2 are complete, recurrent groundwork is implemented and still being hardened, and convolutional/spatial groundwork is in progress.
+  - Plan: [ONNX_EXPORT_PLAN.md](ONNX_EXPORT_PLAN.md) [WIP]
+  - Current internal state: Phase 0-2 are complete, recurrent groundwork is implemented and still being hardened, and convolutional/spatial groundwork is in progress.
 
 **Recommended timing:**
 
@@ -142,7 +156,7 @@ This plan is large and can run as a **parallel lane** after Phase 1, but it shou
 **Outcome:** evo-devo / hyper-scale capabilities that build on top of all prior infrastructure.
 
 - HyperEvoDevo MorphoNEAT
-   - Plan: [HyperEvoDevoMorphoNEAT.md](HyperEvoDevoMorphoNEAT.md) [PLANNED]
+  - Plan: [HyperEvoDevoMorphoNEAT.md](HyperEvoDevoMorphoNEAT.md) [PLANNED]
 
 **Why last:** this work depends heavily on the Memory Optimization track (Track 2 in that plan) and benefits from stable NEAT correctness, deterministic activation semantics, and robust serialization/checkpointing.
 
@@ -160,50 +174,58 @@ Current status: the project is still in **Phase 0**, with both demos solid split
 This is the full `plans/` inventory flattened into execution order so every plan
 file has a visible place in the roadmap.
 
+This inventory excludes [README.md](README.md), which is the plans index rather
+than a roadmap-tracked plan file.
+
 ### Phase 0 inventory
 
 1. [Flappy_Bird_Folder_Documentation_Pass.md](Flappy_Bird_Folder_Documentation_Pass.md) [DONE]
 2. [architecture-solid-split.plans.md](architecture-solid-split.plans.md) [WIP]
 3. [methods-solid-split.plans.md](methods-solid-split.plans.md) [DONE]
 4. [methods-docs.plans.md](methods-docs.plans.md) [DONE]
-5. [docs.plans.md](docs.plans.md) [WIP]
+5. [neat-docs.plans.md](neat-docs.plans.md) [WIP]
 6. [utils-docs.plans.md](utils-docs.plans.md) [DONE]
-7. [src-no-explicit-any-cleanup.plans.md](src-no-explicit-any-cleanup.plans.md) [DONE]
-8. [ES2023 migration](ES2023%20migration) [PLANNED]
+7. [neat-test-surface-repair.plans.md](neat-test-surface-repair.plans.md) [DONE]
+8. [asciiMaze-typescript-repair.plans.md](asciiMaze-typescript-repair.plans.md) [DONE]
+9. [generate-docs-solid-split.plans.md](generate-docs-solid-split.plans.md) [DONE]
+10. [render-docs-html-solid-split.plans.md](render-docs-html-solid-split.plans.md) [DONE]
+11. [analyze-trace-solid-split.plans.md](analyze-trace-solid-split.plans.md) [DONE]
+12. [src-no-explicit-any-cleanup.plans.md](src-no-explicit-any-cleanup.plans.md) [DONE]
+13. [ES2023 migration](ES2023%20migration) [PLANNED]
 
 ### Phase 1 inventory
 
-9. [neat.plans.md](neat.plans.md) [PLANNED]
-10. [Stable_Activation_Ordering_and_Explicit_IO_Roles.md](Stable_Activation_Ordering_and_Explicit_IO_Roles.md) [PLANNED]
+14. [neat.plans.md](neat.plans.md) [PLANNED]
+15. [Stable_Activation_Ordering_and_Explicit_IO_Roles.md](Stable_Activation_Ordering_and_Explicit_IO_Roles.md) [PLANNED]
 
 ### Phase 2 inventory
 
-11. [Architecture_Primitives_Node_Group_Layer.md](Architecture_Primitives_Node_Group_Layer.md) [PLANNED]
-12. [Construct_From_Parts_Graph_Assembly.md](Construct_From_Parts_Graph_Assembly.md) [PLANNED]
-13. [Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md](Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md) [PLANNED]
+16. [Architecture_Primitives_Node_Group_Layer.md](Architecture_Primitives_Node_Group_Layer.md) [PLANNED]
+17. [Construct_From_Parts_Graph_Assembly.md](Construct_From_Parts_Graph_Assembly.md) [PLANNED]
+18. [Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md](Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md) [PLANNED]
 
 ### Phase 3 inventory
 
-14. [Browser_Build_and_CDN_Distribution.md](Browser_Build_and_CDN_Distribution.md) [PLANNED]
-15. [Interactive_Examples_and_Learning_Path.md](Interactive_Examples_and_Learning_Path.md) [PLANNED]
-16. [Network_Visualization_Export_Schema.md](Network_Visualization_Export_Schema.md) [PLANNED]
+19. [Browser_Build_and_CDN_Distribution.md](Browser_Build_and_CDN_Distribution.md) [PLANNED]
+20. [Interactive_Examples_and_Learning_Path.md](Interactive_Examples_and_Learning_Path.md) [PLANNED]
+21. [Network_Visualization_Export_Schema.md](Network_Visualization_Export_Schema.md) [PLANNED]
 
 ### Phase 4 inventory
 
-17. [Standalone_Inference_Export.md](Standalone_Inference_Export.md) [PLANNED]
-18. [Worker_Friendly_Network_Serialization_Fastpath.md](Worker_Friendly_Network_Serialization_Fastpath.md) [PLANNED]
-19. [Turnkey_Multithread_Evaluation_API.md](Turnkey_Multithread_Evaluation_API.md) [PLANNED]
-20. [Population_Save_Resume_and_Checkpointing.md](Population_Save_Resume_and_Checkpointing.md) [PLANNED]
-21. [Evolution_Training_Interoperability_Contracts.md](Evolution_Training_Interoperability_Contracts.md) [PLANNED]
+22. [Standalone_Inference_Export.md](Standalone_Inference_Export.md) [PLANNED]
+23. [Worker_Friendly_Network_Serialization_Fastpath.md](Worker_Friendly_Network_Serialization_Fastpath.md) [PLANNED]
+24. [Turnkey_Multithread_Evaluation_API.md](Turnkey_Multithread_Evaluation_API.md) [PLANNED]
+25. [Population_Save_Resume_and_Checkpointing.md](Population_Save_Resume_and_Checkpointing.md) [PLANNED]
+26. [Evolution_Training_Interoperability_Contracts.md](Evolution_Training_Interoperability_Contracts.md) [PLANNED]
 
 ### Phase 5 inventory
 
-22. [Memory_Optimization.md](Memory_Optimization.md) [WIP]
+27. [Memory_Optimization.md](Memory_Optimization.md) [WIP]
 
 ### Phase 6 inventory
 
-23. [ONNX_EXPORT_PLAN.md](ONNX_EXPORT_PLAN.md) [WIP]
+28. [ONNX_EXPORT_PLAN.md](ONNX_EXPORT_PLAN.md) [WIP]
 
 ### Phase 7 inventory
 
-24. [HyperEvoDevoMorphoNEAT.md](HyperEvoDevoMorphoNEAT.md) [PLANNED]
+29. [HyperEvoDevoMorphoNEAT.md](HyperEvoDevoMorphoNEAT.md) [PLANNED]

package/plans/analyze-trace-solid-split.plans.md

@@ -0,0 +1,66 @@
+# Analyze Trace SOLID Split
+
+**Status:** [DONE]
+
+## Scope
+
+- Folderize the trace analyzer into [scripts/analyze-trace](../scripts/analyze-trace) with a stable entrypoint at [scripts/analyze-trace/analyze-trace.ts](../scripts/analyze-trace/analyze-trace.ts).
+- Keep `npm run trace:analyze` stable by retargeting it to the folder-owned entrypoint instead of leaving a flat compatibility shim.
+- Improve JSDoc, naming clarity, and deterministic report assembly without changing the report's overall scope.
+
+## Current state
+
+- Split root: `scripts/analyze-trace/`
+- README inventory for `scripts/`: none under `scripts/**/README.md`
+- Relevant plan: `n/a` (tooling-only trace analyzer tidy; no direct roadmap lane)
+- Stable entrypoint: `scripts/analyze-trace/analyze-trace.ts`
+- Landed folder files:
+  - `scripts/analyze-trace/analyze-trace.ts`
+  - `scripts/analyze-trace/analyze-trace.constants.ts`
+  - `scripts/analyze-trace/analyze-trace.types.ts`
+  - `scripts/analyze-trace/analyze-trace.shared.ts`
+  - `scripts/analyze-trace/analyze-trace.io.ts`
+  - `scripts/analyze-trace/analyze-trace.analysis.ts`
+  - `scripts/analyze-trace/analyze-trace.report.ts`
+- Closed issues in this step:
+  - CLI parsing, trace loading, analysis, shared helpers, and report rendering no longer live in one file,
+  - the split now uses a real folder boundary instead of scattering module files at the scripts root,
+  - deterministic sort tie-breaks now make equal-duration sections more stable across runs,
+  - the stable min/max timestamp scan remains single-pass for large traces.
+
+## Coverage backlog
+
+### [DONE] Folder-owned analyzer split
+
+- Moved the analyzer into [scripts/analyze-trace](../scripts/analyze-trace) and retargeted `npm run trace:analyze` to [scripts/analyze-trace/analyze-trace.ts](../scripts/analyze-trace/analyze-trace.ts).
+- Separated constants, contracts, shared utility helpers, CLI/file I/O, analysis passes, and text-report rendering inside the folder boundary.
+- Preserved the existing report sections while making the orchestration flow read as resolve -> load -> analyze -> print.
+
+### [DONE] Educational docs follow-up
+
+- Added educational JSDoc to the folder-owned constants, contracts, helpers, and report surface so future trace-tooling changes can start from an intentional boundary map instead of a single oversized file.
+
+## Validation
+
+- File diagnostics: clean for the touched `scripts/analyze-trace/*.ts` files.
+- `npx tsc --noEmit -p tsconfig.docs.json`
+- `npm run trace:analyze -- test/examples/flappy_bird/Trace-20260309T191949.json --top=5`
+
+## Immediate next steps
+
+- No further split work is queued for this boundary right now.
+- Future analyzer changes should continue inside `scripts/analyze-trace/` instead of re-growing a flat scripts-root boundary.
+
+## Handoff query
+
+```text
+Continue from the current repo state only. Do not rely on prior chat history.
+
+Use solid-split for #file:analyze-trace.
+Plan: plans/analyze-trace-solid-split.plans.md.
+Current boundary: scripts/analyze-trace/.
+Completed context: scripts has no local README surface, scripts/analyze-trace/analyze-trace.ts is the stable CLI entrypoint, and the analyzer now splits responsibilities across constants, types, shared helpers, CLI/file I/O, analysis, and report rendering inside one owned folder.
+Repo standard: direct-path migration with no compatibility shims by default, and the small-chapter mindset applies to scripts/tooling boundaries.
+Required validations: file diagnostics for touched files, npx tsc --noEmit -p tsconfig.docs.json, then npm run trace:analyze -- test/examples/flappy_bird/Trace-20260309T191949.json --top=5.
+Worktree caution: there may already be unrelated generated README drift elsewhere in the repo.
+```

package/plans/architecture-solid-split.plans.md

@@ -166,7 +166,7 @@ root. Keep exactly one boundary pass active at a time.
   hides the flat root compatibility files from the generated architecture root
   README while still using the configured intro summary as the directory-level
   opening.
-- [scripts/generate-docs.ts](../scripts/generate-docs.ts) now resolves a
+- [scripts/generate-docs/generate-docs.ts](../scripts/generate-docs/generate-docs.ts) now resolves a
   configured intro file from the full sorted file list rather than only the
   visible file list, which allows hidden compatibility facades to remain the
   source of the root chapter introduction.
@@ -180,7 +180,7 @@ root. Keep exactly one boundary pass active at a time.
 
 1. Network class seam work is complete enough for audit mode.
 2. The public-surface docs cleanup is complete; only reopen class-owned split
-  work if the refreshed README still exposes a concrete overloaded seam.
+   work if the refreshed README still exposes a concrete overloaded seam.
 
 ### [PLANNED] Deferred Questions
 
@@ -195,7 +195,7 @@ root. Keep exactly one boundary pass active at a time.
   > Proceed
 - Decide at the end of the active network workstream whether a separate
   architecture-wide README size and thin-doc audit should become its own plan.
-  > Elaborate? We want full documentation 
+  > Elaborate? We want full documentation
 
 ## Coverage Backlog
 
@@ -295,8 +295,7 @@ entry records the minimal extent of completed work and the current stop point.
   [src/architecture/network/onnx/import/network.onnx.import-fused-recurrent.types.ts](../src/architecture/network/onnx/import/network.onnx.import-fused-recurrent.types.ts)
   so the root compatibility barrel no longer owns the emitted LSTM/GRU replay
   context family.
--
-  [src/architecture/network/onnx/import/network.onnx.import-fused-recurrent.utils.ts](../src/architecture/network/onnx/import/network.onnx.import-fused-recurrent.utils.ts)
+- [src/architecture/network/onnx/import/network.onnx.import-fused-recurrent.utils.ts](../src/architecture/network/onnx/import/network.onnx.import-fused-recurrent.utils.ts)
   now reads those importer-only contracts from the local import chapter while
   the root file keeps only the shared `NodeInternals` and `OnnxLayerFactory`
   bridge types.
@@ -310,12 +309,10 @@ entry records the minimal extent of completed work and the current stop point.
   [src/architecture/network/onnx/import/README.md](../src/architecture/network/onnx/import/README.md)
   now opens with the import pipeline story instead of inheriting its chapter
   introduction from the runtime-factory leaf types file.
--
-  [src/architecture/network/onnx/import/docs.order.json](../src/architecture/network/onnx/import/docs.order.json)
+- [src/architecture/network/onnx/import/docs.order.json](../src/architecture/network/onnx/import/docs.order.json)
   now pins the import flow file as the intro source and keeps the generated
   reading order aligned to the actual reconstruction pipeline.
--
-  [src/architecture/network/onnx/import/network.onnx.import-flow.utils.ts](../src/architecture/network/onnx/import/network.onnx.import-flow.utils.ts)
+- [src/architecture/network/onnx/import/network.onnx.import-flow.utils.ts](../src/architecture/network/onnx/import/network.onnx.import-flow.utils.ts)
   now explains the staged restore questions that link the neighboring runtime,
   weight, activation, orchestration, and fused-recurrent chapters together.
 - Validation completed with `npx tsc --noEmit -p tsconfig.json` and
@@ -328,12 +325,10 @@ entry records the minimal extent of completed work and the current stop point.
   now opens with an explicit chapter map that tells readers when to continue
   into the `export/`, `import/`, and `schema/` subchapters versus when to use
   the root compatibility barrels.
--
-  [src/architecture/network/onnx/docs.order.json](../src/architecture/network/onnx/docs.order.json)
+- [src/architecture/network/onnx/docs.order.json](../src/architecture/network/onnx/docs.order.json)
   now pins the root ONNX reading order so the public entrypoint stays first and
   the thinner root utility barrel appears before the larger root types barrel.
--
-  [src/architecture/network/onnx/network.onnx.ts](../src/architecture/network/onnx/network.onnx.ts)
+- [src/architecture/network/onnx/network.onnx.ts](../src/architecture/network/onnx/network.onnx.ts)
   now explains why the root chapter exists, how the folder is split, and how a
   contributor should navigate the remaining compatibility surfaces.
 - Validation completed with `npx tsc --noEmit -p tsconfig.json` and
@@ -384,8 +379,7 @@ entry records the minimal extent of completed work and the current stop point.
   instead of dropping directly into the much larger
   [src/architecture/network/network.types.ts](../src/architecture/network/network.types.ts)
   shelf.
--
-  [src/architecture/network/docs.order.json](../src/architecture/network/docs.order.json)
+- [src/architecture/network/docs.order.json](../src/architecture/network/docs.order.json)
   now pins the chapter intro to the public `Network` class and keeps the
   reading order aligned to public orchestration first, compatibility utilities
   second, and the large root types shelf last.

package/plans/asciiMaze-typescript-repair.plans.md

@@ -39,4 +39,4 @@ Repair the remaining `test/examples/asciiMaze/**` TypeScript diagnostics in
 ```text
 Continue from the current repo state only. Do not rely on prior chat history.
 Work from plans/asciiMaze-typescript-repair.plans.md. The ASCII Maze TypeScript repair pass is complete: browser-entry, evolution-engine, setup/pruning, and telemetry compatibility seams were aligned, `npx tsc --noEmit -p tsconfig.test.json` is green, and `npm test` passes. Preserve unrelated user changes and only reopen this area if new diagnostics appear.
-```
+```