@reicek/neataptic-ts 0.1.25 → 0.1.26

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.

package/plans/neat-docs.plans.md

@@ -9,13 +9,16 @@ The source of truth is the generated documentation fed by [src/neat.ts](../src/n
 which renders into [src/README.md](../src/README.md) after `npm run docs`.
 
 Primary reader:
+
 - first-time NeatapticTS readers who want to understand how the top-level NEAT controller works before diving into chaptered internals.
 
 Primary surfaces:
+
 - [src/neat.ts](../src/neat.ts)
 - [src/README.md](../src/README.md)
 
 Out of scope for this pass:
+
 - hand-editing generated READMEs under `src/`
 - adding external images or citations unless a concrete teaching gap requires them
 - broad rewrites of every `src/neat/**` chapter README
@@ -29,21 +32,26 @@ Out of scope for this pass:
 ## Session Log
 
 ### Foundation
+
 - Strengthened [src/neat.ts](../src/neat.ts) so the generated root story in [src/README.md](../src/README.md) reads as a clearer controller overview.
 
 ### Generator follow-up
-- The docs generator work is complete enough for now: [scripts/generate-docs.ts](../scripts/generate-docs.ts) supports per-folder ordering controls through `docs.order.json`, and the shared-speciation pilot is already live in [src/neat/speciation/shared/docs.order.json](../src/neat/speciation/shared/docs.order.json).
+
+- The docs generator work is complete enough for now: [scripts/generate-docs/generate-docs.ts](../scripts/generate-docs/generate-docs.ts) supports per-folder ordering controls through `docs.order.json`, and the shared-speciation pilot is already live in [src/neat/speciation/shared/docs.order.json](../src/neat/speciation/shared/docs.order.json).
 
 ### Latest completed chapter work
+
 - Recent source-first passes strengthened [src/neat/shared/neat.shared.types.ts](../src/neat/shared/neat.shared.types.ts), [src/neat/neat.constants.ts](../src/neat/neat.constants.ts), [src/neat/cache/cache.ts](../src/neat/cache/cache.ts), [src/neat/compat/compat.ts](../src/neat/compat/compat.ts), [src/neat/harness/neat.harness.types.ts](../src/neat/harness/neat.harness.types.ts), [src/neat/init/neat.init.ts](../src/neat/init/neat.init.ts), [src/neat/helpers/neat.helpers.ts](../src/neat/helpers/neat.helpers.ts), and [src/neat/rng/rng.ts](../src/neat/rng/rng.ts); the RNG root now distinguishes caller-owned randomness from controller-owned replay state more explicitly, and the root [src/README.md](../src/README.md) plus [src/neat.ts](../src/neat.ts) story still holds up against the current pedagogical standard. Docs regeneration and TypeScript validation should be kept on every new pass.
 - A bounded root-surface polish split then moved the root compatibility alias shelf into [src/neat/neat.types.ts](../src/neat/neat.types.ts), moved the public defaults shelf into [src/neat/neat.defaults.constants.ts](../src/neat/neat.defaults.constants.ts), and centralized the empty diversity fallback in [src/neat/diversity/diversity.ts](../src/neat/diversity/diversity.ts); [src/README.md](../src/README.md) still presents the stable public root story while [src/neat/README.md](../src/neat/README.md) now carries the deeper root-types and root-defaults chapter docs.
 
 Remaining gaps:
+
 - Most remaining weaknesses are now small chapter-quality revisits, not untouched surfaces.
 - Generator limits still show up in some larger or re-export-heavy chapters, so only use `docs.order.json` when ordering is the real blocker.
 - Keep prioritizing compact runtime, facade, or policy boundaries that still read more like shelves than chapters.
 
 Next step:
+
 - Re-read [src/neat/lineage/README.md](../src/neat/lineage/README.md) and [src/neat/lineage/lineage.ts](../src/neat/lineage/lineage.ts) to decide whether the lineage root is now the next weakest compact controller-facing boundary after the RNG pass.
 
 ## Handoff Prompt

package/plans/neat-test-surface-repair.plans.md

@@ -35,4 +35,4 @@ features and root helper facades compile against the existing test suite.
 ```text
 Continue from the current repo state only. Do not rely on prior chat history.
 The NEAT public-surface repair tracked in plans/neat-test-surface-repair.plans.md is complete. Do not make further NEAT-surface changes unless new evidence appears. If follow-up work is needed, start a separate pass for the remaining TypeScript diagnostics under test/examples/asciiMaze/**. Preserve unrelated user changes.
-```
+```

package/plans/render-docs-html-solid-split.plans.md

@@ -0,0 +1,68 @@
+# Render Docs HTML SOLID Split
+
+**Status:** [DONE]
+
+## Scope
+
+- Consolidate the HTML docs renderer into a folder-owned boundary rooted at `scripts/render-docs-html/`.
+- Keep `scripts/render-docs-html.ts` as the stable orchestration entrypoint.
+- Remove the flat `scripts/render-docs-html.sidebar.ts` file once the new direct-path chapter imports are in place.
+- Improve link correctness, sidebar clarity, and docs UX where those issues are exposed by the split.
+
+## Current state
+
+- Split root: `scripts/render-docs-html/` with `scripts/render-docs-html.ts` as the stable orchestration entrypoint
+- README inventory for `scripts/`: none under `scripts/**/README.md`
+- Relevant plan: [plans/Interactive_Examples_and_Learning_Path.md](../plans/Interactive_Examples_and_Learning_Path.md)
+- Relevant repo memory: `/memories/repo/scripts_docs_sidebar_boundary.md`
+- Stable entrypoint: `scripts/render-docs-html.ts`
+- Landed chapter files:
+  - `render-docs-html.assets.ts`
+  - `render-docs-html.mermaid.ts`
+  - `render-docs-html.navigation.ts`
+  - `render-docs-html.pages.ts`
+  - `render-docs-html.shared.ts`
+  - `render-docs-html.types.ts`
+- Closed issues in this step:
+  - nested docs content links now resolve through compiled docs targets or repository URLs instead of remaining raw repo-relative hrefs,
+  - deep sidebar labels now use clearer formatted names instead of collapsing to ambiguous leaf-only segments,
+  - examples-first showcase now collapses to a lighter compact mode away from onboarding/example surfaces.
+
+## Coverage backlog
+
+### [DONE] Consolidated renderer folder split
+
+- Created `scripts/render-docs-html/` with focused chapters for shared helpers, navigation, Mermaid handling, page rendering, static assets, and shared contracts.
+- Kept `scripts/render-docs-html.ts` orchestration-first and moved the heavy logic behind direct chapter imports.
+- Deleted `scripts/render-docs-html.sidebar.ts` after the direct-path migration landed.
+- Folded link-rewrite fixes and targeted sidebar UX improvements into the same step.
+
+### [DONE] Educational docs follow-up
+
+- Completed the required `educational-docs` follow-up on the touched renderer boundary.
+- Strengthened chapter-level documentation and shared type descriptions so the renderer reads as an intentional docs-tooling subsystem rather than a loose helper shelf.
+
+## Validation
+
+- File diagnostics: clean for `scripts/render-docs-html.ts` and all files under `scripts/render-docs-html/`.
+- `npm run docs`: passed.
+
+## Immediate next steps
+
+- No further split work is queued for this boundary right now.
+- Future work should start from `scripts/render-docs-html/` and preserve `scripts/render-docs-html.ts` as the stable entrypoint.
+
+## Handoff query
+
+```text
+Continue from the current repo state only. Do not rely on prior chat history.
+
+Use solid-split for #file:render-docs-html.ts and #file:render-docs-html.sidebar.ts.
+Plan: plans/render-docs-html-solid-split.plans.md.
+Current boundary: scripts/render-docs-html.
+Completed context: scripts has no local README surface, the stable entrypoint remains scripts/render-docs-html.ts, the old flat sidebar file is deleted, and the folder boundary now owns assets, Mermaid handling, navigation, shared helpers, page rendering, and shared contracts.
+If this boundary reopens: continue from the folderized renderer, preserving the improved content-link rewriting and the lighter examples/sidebar behavior instead of recreating flat helper files.
+Repo standard: direct-path migration with no compatibility shims by default, and the small-chapter README pattern applies to scripts/tooling boundaries too.
+Required validations: file diagnostics for touched files, then npm run docs.
+Worktree caution: npm run docs rewrites generated docs outputs and there may already be unrelated generated-file drift in the worktree.
+```

package/plans/src-no-explicit-any-cleanup.plans.md

@@ -172,4 +172,4 @@ Current repo state:
 Next target:
 - No active target in this lane. Reopen only if future edits reintroduce explicit-any debt or new broad lint drift into `src/`.
 - If reopened, begin with a fresh raw scan, `npx eslint src`, and `npx tsc --noEmit -p tsconfig.json` before selecting a new target.
-```
+```

package/plans/utils-docs.plans.md

@@ -8,10 +8,12 @@ This plan tracks educational-docs passes for the small shared utility surfaces
 under [src/utils/README.md](../src/utils/README.md).
 
 Primary reader:
+
 - readers who want to understand support utilities as teaching tools rather
   than as unframed implementation leftovers.
 
 Primary surfaces:
+
 - [src/utils/memory.ts](../src/utils/memory.ts)
 - [src/utils/memory.utils.ts](../src/utils/memory.utils.ts)
 - [src/utils/README.md](../src/utils/README.md)
@@ -19,6 +21,7 @@ Primary surfaces:
 ## Session Log
 
 ### Latest completed chapter work
+
 - Strengthened the root [src/utils/memory.ts](../src/utils/memory.ts) opening so
   the generated [src/utils/README.md](../src/utils/README.md) now explains why
   heuristic memory instrumentation exists, which questions it answers, and how
@@ -33,12 +36,14 @@ Primary surfaces:
   blocking global docs generation.
 
 Remaining gaps:
+
 - The `src/utils` folder is now small and reasonably aligned; future work here
   is more likely to be refinement than rescue.
 - If additional utility modules are added later, keep this plan focused on
   chapter quality instead of growing a long historical log.
 
 Next step:
+
 - Move to the next small cross-cutting folder that still reads more like a
   helper shelf than a chapter, using [src/utils/README.md](../src/utils/README.md)
-  as the quality bar for support modules.
+  as the quality bar for support modules.