@reicek/neataptic-ts 0.1.24 → 0.1.26

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.
-```
+```

package/plans/generate-docs-solid-split.plans.md

@@ -0,0 +1,87 @@
+# Generate Docs SOLID Split
+
+**Status:** [DONE]
+
+## Scope
+
+- Split the docs generator from the old flat [scripts/generate-docs.ts](../scripts/generate-docs/generate-docs.ts) boundary into a folder-owned module under `scripts/`.
+- Keep the `docs:folders:*` CLI behavior stable by updating repo-local callers to the new built entrypoint instead of leaving a flat compatibility shim.
+- Improve source readability with orchestration-first flow, focused helper ownership, and comprehensive JSDoc on the new exported surfaces.
+
+## Current state
+
+- Split root: `scripts/generate-docs/`
+- Nearest README reviewed: `n/a` (no `scripts/**/README.md` files currently exist)
+- Parent README reviewed: `n/a`
+- Relevant plan: [plans/neat-docs.plans.md](../plans/neat-docs.plans.md)
+- Adjacent reference checked: [plans/architecture-solid-split.plans.md](../plans/architecture-solid-split.plans.md)
+- Current boundary: the root entrypoint now delegates to focused chapter files for targets, symbols, ordering, output, constants, state, and shared contracts.
+- Active split frontier: `generate-docs.symbols.ts` and `generate-docs.output.ts` have each grown into their own responsibility clusters and now need direct-path subfolderization.
+
+## Durable rules
+
+- Keep exactly one active workstream section.
+- Prefer direct-path migration to `scripts/generate-docs/generate-docs.ts`; do not leave a flat shim unless a real compatibility need appears.
+- Do not hand-edit generated README files as part of this split.
+- Run docs-tooling validation after the split because this boundary feeds `npm run docs`.
+
+## Target shape
+
+- `scripts/generate-docs/generate-docs.ts` owns CLI orchestration.
+- `scripts/generate-docs/generate-docs.types.ts` owns shared docs-generator contracts.
+- `scripts/generate-docs/generate-docs.constants.ts` owns stable constants and target definitions.
+- `scripts/generate-docs/generate-docs.state.ts` owns shared ts-morph and docs-order cache state.
+- `scripts/generate-docs/generate-docs.targets.ts` owns target resolution and source-tree preparation.
+- `scripts/generate-docs/generate-docs.symbols.ts` owns symbol collection, JSDoc extraction, and dedupe rules.
+- `scripts/generate-docs/generate-docs.order.ts` owns `docs.order.json` loading, validation, caching, and warnings.
+- `scripts/generate-docs/generate-docs.output.ts` owns README rendering, folder-index rendering, and file emission.
+
+## Coverage backlog
+
+### [DONE] Generator root split
+
+- Landed the folder-owned module at [scripts/generate-docs/generate-docs.ts](../scripts/generate-docs/generate-docs.ts) with dedicated chapter files for constants, types, state, targets, symbols, ordering, and output.
+- Retargeted the repo-local docs scripts to `dist-docs/scripts/generate-docs/generate-docs.js` so the split uses direct-path migration with no flat compatibility shim.
+- Updated the existing plan references that pointed at the deleted flat script path.
+- Completed the required educational-docs follow-up by adding chapter-level source introductions to the new files so maintainers can read the split as a guided boundary map instead of a raw helper shelf.
+
+### [DONE] Symbols and output chapter split
+
+- Reopen the generator boundary to move `generate-docs.symbols.ts` into `scripts/generate-docs/symbols/` and `generate-docs.output.ts` into `scripts/generate-docs/output/`.
+- Keep direct-path migration: update repo-local imports to the new subfolder entrypoints and delete the flat files after validations pass.
+- Keep the new chapter roots orchestration-first, with narrower helper files for collection/rendering/signature work in the symbols boundary and README/index ordering work in the output boundary.
+- Completed the direct-path move into `scripts/generate-docs/symbols/` and `scripts/generate-docs/output/`, removed the flat chapter files, and retargeted the root generator imports to the new nested entrypoints.
+- Fixed the post-split behavioral regressions in the output boundary so `introFile` once again controls directory intro promotion and folder-index nodes keep correct source and link paths.
+- Completed the mandatory educational-docs follow-up with contract-level JSDoc covering signature storage, file-summary precedence, intro promotion, and fallback ordering.
+
+## Validation
+
+- Completed in prior step:
+  - `npm run docs:build-scripts`
+  - `npm run docs`
+  - `npm run docs:build-scripts` after the educational-docs follow-up
+- Completed for this step:
+  - `npm run docs:build-scripts`
+  - `npm run docs`
+  - `npm run docs:build-scripts` after the post-validation educational-docs follow-up
+
+## Immediate next steps
+
+- No further split work is queued in this boundary right now.
+- Future work, if needed, should start from the nested `symbols/` and `output/` folders rather than recreating flat chapter files.
+
+## Handoff query
+
+```text
+Continue docs-tooling work from the current repo state only. Do not rely on prior chat history.
+
+Plan: plans/generate-docs-solid-split.plans.md
+Current boundary: scripts/generate-docs/
+Repo standard: migrate directly to scripts/generate-docs/generate-docs.ts with no compatibility shim by default, and keep the split in small responsibility chapters.
+Small-chapter standard: this applies to scripts and tooling boundaries too, not only library code.
+Already covered: the old flat generator script was removed, package.json now points at dist-docs/scripts/generate-docs/generate-docs.js, and the current root chapter files own targets, symbols, ordering, output, state, constants, and types.
+Next task if this boundary reopens: continue from the nested scripts/generate-docs/symbols/ and scripts/generate-docs/output/ folders, preserving direct-path imports and the current docs-order behavior.
+Required validations: npm run docs:build-scripts, npm run docs.
+Worktree caution: .github/copilot-instructions.md may already have unrelated local edits.
+Continue from the current repo state only. Do not rely on prior chat history.
+```

package/plans/methods-docs.plans.md

@@ -8,10 +8,12 @@ This plan tracks educational-docs passes for the shared method vocabulary under
 [src/methods/README.md](../src/methods/README.md).
 
 Primary reader:
+
 - readers who want the reusable training and evolutionary method families to
   read like a guided policy shelf rather than a raw export list.
 
 Primary surfaces:
+
 - [src/methods/methods.ts](../src/methods/methods.ts)
 - [src/methods/cost/cost.ts](../src/methods/cost/cost.ts)
 - [src/methods/rate/rate.ts](../src/methods/rate/rate.ts)
@@ -25,10 +27,12 @@ Primary surfaces:
 ### Methods root chapter pass
 
 Goals:
+
 - Make the generated [src/methods/README.md](../src/methods/README.md) open as
   a guided chapter instead of a raw export list.
 
 Progress:
+
 - Added a barrel-led introduction in
   [src/methods/methods.ts](../src/methods/methods.ts) so the chapter now opens
   with the shared method-family map.
@@ -38,18 +42,21 @@ Progress:
   framing and diagram-justified guidance.
 
 Decision:
+
 - Keep future methods work proportional and continue one family chapter at a
   time rather than reopening the entire folder.
 
 ### Activation chapter pass
 
 Goals:
+
 - Make the activation family read more like a chooser and less like a flat
   list of transfer-curve helpers.
 - Tighten the older symbol-level prose in the utility shelf without changing
   runtime behavior.
 
 Progress:
+
 - Added a compact family map in
   [src/methods/activation/activation.ts](../src/methods/activation/activation.ts)
   so the generated activation chapter shows the main activation clusters before
@@ -61,18 +68,21 @@ Progress:
   transforms.
 
 Decision:
+
 - Leave the deeper per-symbol registry cleanup for a later polish pass and keep
   moving through the thin structural chapters one family at a time.
 
 ### Gating chapter pass
 
 Goals:
+
 - Make the gating family read like a structural chooser instead of a short
   constant shelf.
 - Clarify how `INPUT`, `OUTPUT`, and `SELF` differ so readers can pick a gate
   position by intent instead of memorizing names.
 
 Progress:
+
 - Reframed [src/methods/gating/gating.ts](../src/methods/gating/gating.ts)
   around the placement question the family answers, with stronger source-first
   chooser guidance for the three gate positions.
@@ -80,6 +90,7 @@ Progress:
   surface each option creates and includes a minimal example for quick recall.
 
 Remaining gaps:
+
 - The sibling structural family for connection policies is still thinner than
   the rest of the methods shelf and likely needs the same chapter-first framing.
 - If the methods root chapter gets another pass later, its short gating summary
@@ -87,18 +98,21 @@ Remaining gaps:
   connection pass.
 
 Next step:
+
 - Move to the connection family next and give its structural wiring vocabulary
   the same chooser-first treatment used for gating.
 
 ### Connection chapter pass
 
 Goals:
+
 - Make the connection family read like a wiring-policy chooser instead of a
   terse list of topology names.
 - Clarify when dense connectivity, dense-without-self-links, and one-to-one
   alignment are the right structural defaults.
 
 Progress:
+
 - Reframed [src/methods/connection/connection.ts](../src/methods/connection/connection.ts)
   around the structural question the family answers, with stronger source-first
   guidance for the three built-in wiring patterns.
@@ -107,12 +121,14 @@ Progress:
   recall.
 
 Remaining gaps:
+
 - The thin structural families are now better aligned, so future work here is
   more likely to be polish than rescue.
 - If the methods root chapter gets another pass later, its short structural
   summaries for both gating and connection can be harmonized again for tone.
 
 Next step:
+
 - Re-read the methods root chapter and decide whether the next highest-value
   pass is a small root-summary alignment pass or a deeper polish pass on one of
   the larger method families.
@@ -120,12 +136,14 @@ Next step:
 ### Methods root alignment pass
 
 Goals:
+
 - Re-align the root methods introduction so its structural summary matches the
   stronger gating and connection chapters.
 - Keep the top-level chapter compact while making the difference between
   routing control and wiring layout explicit.
 
 Progress:
+
 - Tightened [src/methods/methods.ts](../src/methods/methods.ts) so the root
   chapter now describes `gating` and `groupConnection` as different parts of
   the structural vocabulary instead of bundling them together too loosely.
@@ -134,24 +152,28 @@ Progress:
   opening stays compact and source-first.
 
 Remaining gaps:
+
 - The methods root is now aligned with the thin structural chapters, so the
   next useful pass is more likely to be selective polish than root framing.
 - Larger families such as mutation or rate may still benefit from later
   refinement, but they no longer block the root chapter from reading clearly.
 
 Next step:
+
 - Choose the next highest-value polish pass among the larger method families,
   or stop here if the methods shelf is sufficiently aligned for now.
 
 ### Rate and mutation polish pass
 
 Goals:
+
 - Smooth the generated docs for two larger method-adjacent chapters without
   reopening their runtime behavior.
 - Remove remaining generated-doc rough edges such as duplicated framing and
   awkward parameter prose.
 
 Progress:
+
 - Tightened [src/methods/rate/rate.ts](../src/methods/rate/rate.ts) so the
   class-level chapter no longer repeats the full module opening and instead
   acts like a practical chooser for schedule builders.
@@ -164,10 +186,12 @@ Progress:
   generated mutation chapter reads less like raw annotation output.
 
 Decision:
+
 - Stop the methods documentation lane here for now; the root and the highest-
   leverage family chapters now read coherently enough that further work is
   polish, not structural rescue.
 
 Next step:
+
 - Pause this plan and revisit only if a later docs pass exposes a specific
-  regression, stale generated wording, or a newly expanded method family.
+  regression, stale generated wording, or a newly expanded method family.

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

@@ -43,31 +43,31 @@ each concept into its own folder-based boundary.
 ## Latest Pass
 
 - Folderized the methods surface into chapter folders for `activation`, `cost`,
-    `rate`, `selection`, `mutation`, `crossover`, `gating`, and `connection`.
+  `rate`, `selection`, `mutation`, `crossover`, `gating`, and `connection`.
 - Migrated repo-local imports to direct folder paths and removed the stale flat
-    `src/methods/mutation.ts` file that was still being compiled after the move.
+  `src/methods/mutation.ts` file that was still being compiled after the move.
 - Updated `src/methods/methods.ts` to remain the root public facade and updated
-    root ordering via `src/methods/docs.order.json`.
+  root ordering via `src/methods/docs.order.json`.
 - Added chapter-level ordering configs for `activation`, `cost`, and `rate` so
-    their nested READMEs open from the public facade files rather than utility
-    helpers.
+  their nested READMEs open from the public facade files rather than utility
+  helpers.
 - Updated `.github/skills/educational-docs/SKILL.md` so oversized generated
-    folder READMEs now point toward `solid-split` instead of continuing to grow
-    monolithically.
+  folder READMEs now point toward `solid-split` instead of continuing to grow
+  monolithically.
 - Regenerated docs and verified the generated openings for
-    `src/methods/README.md`, `src/methods/activation/README.md`,
-    `src/methods/cost/README.md`, and `src/methods/rate/README.md`.
+  `src/methods/README.md`, `src/methods/activation/README.md`,
+  `src/methods/cost/README.md`, and `src/methods/rate/README.md`.
 - Final validation completed with `npm run docs` and
-    `npx tsc --noEmit -p tsconfig.json`.
+  `npx tsc --noEmit -p tsconfig.json`.
 
 ## Handoff State
 
 - The split is complete and the root methods README now reads as a chapter map
-    rather than a monolithic flat file dump.
+  rather than a monolithic flat file dump.
 - Nested method READMEs are generated from source-first JSDoc and should be
-    maintained by editing the owning source files, not the generated READMEs.
+  maintained by editing the owning source files, not the generated READMEs.
 - If a future methods family starts to feel oversized again, prefer another
-    bounded folder split over expanding the root README.
+  bounded folder split over expanding the root README.
 
 ## Done Criteria
 
@@ -75,4 +75,4 @@ each concept into its own folder-based boundary.
 - Repo-local imports point at the new direct folder paths.
 - `src/methods/README.md` becomes smaller because chapter content moves into nested folder READMEs.
 - The educational-docs skill explicitly points large monolithic README surfaces toward `solid-split`.
-- The boundary can be resumed safely from this plan alone.
+- The boundary can be resumed safely from this plan alone.