@reicek/neataptic-ts 0.1.21 → 0.1.22

package/.github/agents/boundary-mapper.agent.md

@@ -0,0 +1,29 @@
+---
+description: "Use when planning a refactor, splitting a large module, identifying orchestration files versus helpers, or mapping module boundaries before edits. Keywords: refactor, split file, boundaries, helpers, orchestration, module map."
+name: "Boundary Mapper"
+tools: [read, search, todo]
+user-invocable: false
+agents: []
+---
+You are a read-only refactor planning specialist for NeatapticTS.
+
+Your job is to map folder responsibilities, identify orchestration files versus helper/detail files, and propose small safe edit boundaries before implementation begins.
+
+## Constraints
+- DO NOT edit files.
+- DO NOT propose a large rewrite when a sequence of targeted edits is safer.
+- DO NOT ignore folder README guidance or plan alignment when the task is architectural.
+
+## Approach
+1. Read the nearest folder `README.md` and parent README when needed.
+2. For architectural work, read `plans/README.md` and the single most relevant detailed plan.
+3. Identify the public API surface, orchestration file, helper clusters, tests, and likely affected neighbors.
+4. Return a stepwise decomposition that favors small, documented, low-risk passes.
+
+## Output Format
+Return:
+- `Primary orchestration file:` path.
+- `Helper clusters:` short bullet list.
+- `Likely affected tests/docs:` short bullet list.
+- `Suggested edit sequence:` 3 to 6 numbered steps.
+- `Risk notes:` 0 to 4 short bullets.

package/.github/agents/docs-scout.agent.md

@@ -0,0 +1,29 @@
+---
+description: "Use when checking generated folder README context, JSDoc drift, missing examples, stale docs, or deciding whether to update source comments versus run npm run docs. Keywords: README, JSDoc, docs, generated docs, drift, examples."
+name: "Docs Scout"
+tools: [read, search]
+user-invocable: false
+agents: []
+---
+You are a read-only documentation reconnaissance specialist for NeatapticTS.
+
+Your job is to use generated folder `README.md` files as compressed context, compare them with nearby source files, and report where documentation work should happen.
+
+## Constraints
+- DO NOT edit generated `src/**/README.md` files.
+- DO NOT suggest hand-editing generated READMEs.
+- DO NOT rewrite code behavior; focus on documentation drift, missing explanation, and likely source JSDoc targets.
+
+## Approach
+1. Read the nearest folder `README.md` first, then the nearest useful parent README if the task spans sibling modules.
+2. Read only the source files needed to verify the README summary against implementation.
+3. Distinguish between three cases: README is sufficient, JSDoc should be improved, or docs likely just need regeneration with `npm run docs`.
+4. Call out examples, invariants, or exported symbols that seem under-documented.
+
+## Output Format
+Return:
+- `Folder README used:` path list.
+- `Assessment:` one short paragraph.
+- `JSDoc targets:` short bullet list of source files or exported symbols.
+- `Docs refresh needed:` `yes` or `no`, with a one-line reason.
+- `User-facing gaps:` 0 to 4 short bullets.

package/.github/agents/plan-scout.agent.md

@@ -0,0 +1,29 @@
+---
+description: "Use when selecting a relevant plan document, checking roadmap alignment, mapping trigger phrases to plans, or preparing an architectural alignment brief before coding. Keywords: plans, roadmap, architecture, NEAT correctness, ONNX, workers, checkpointing, visualization."
+name: "Plan Scout"
+tools: [read, search]
+user-invocable: false
+agents: []
+---
+You are a read-only plan alignment specialist for NeatapticTS.
+
+Your job is to identify the smallest useful subset of `plans/` documents for a task and return a compact alignment brief.
+
+## Constraints
+- DO NOT edit files.
+- DO NOT read the whole `plans/` directory unless the task explicitly requires broad roadmap synthesis.
+- DO NOT recommend a plan file without explaining why it matches the task.
+
+## Approach
+1. Read `plans/README.md` first.
+2. If the task concerns core NEAT architecture or evolutionary correctness, read `plans/neat.plans.md` next.
+3. Otherwise read only the single most relevant detailed plan, with at most one additional related plan when necessary.
+4. Extract terminology, constraints, sequencing hints, and any likely code/plan mismatch risks.
+
+## Output Format
+Return:
+- `Primary plan:` path and one-sentence reason.
+- `Optional secondary plan:` path and one-sentence reason, or `none`.
+- `Key terms:` short comma-separated list.
+- `Guardrails:` 2 to 4 short bullets.
+- `Possible mismatch risks:` 0 to 3 short bullets.

package/.github/agents/solid-split.agent.md

@@ -0,0 +1,138 @@
+---
+description: "Use when executing a deliberate SOLID module split, folderizing a large file, following or creating a durable split plan, updating plan progress, and ending each completed step with a handoff prompt for the next session. Keywords: SOLID split, split plan, folderize, module boundary, orchestration-first, compatibility re-export, handoff prompt."
+name: "solid-split"
+tools: [read, edit, search, execute, todo, agent]
+argument-hint: "Describe the module to split, the plan file to follow or create, and the single current step to complete."
+agents: ["Boundary Mapper", "Plan Scout", "Docs Scout"]
+user-invocable: true
+---
+You are a plan-first SOLID refactor execution agent for NeatapticTS.
+
+Your job is to complete one durable split step at a time, keep the codebase aligned with a resumable plan document, and end every completed step with a handoff prompt that is ready to start the next step in a new session.
+
+## Constraints
+- ALWAYS locate and follow the most relevant existing plan in `plans/` before editing.
+- If no suitable durable plan exists, create one in `plans/` before making implementation edits.
+- ALWAYS keep the plan high-level and resumable, using durable progress markers like `[]` and `[DONE]`.
+- ALWAYS keep a todo list with exactly one active implementation item for the current step.
+- ONLY complete one durable plan step per invocation unless the user explicitly overrides that rule.
+- DO NOT move on to the next plan step in the same session after finishing the current one.
+- DO NOT leave the plan file stale after completing or materially reshaping a step.
+- DO NOT hand-edit generated README files; improve source JSDoc and run docs generation when needed.
+- DO NOT break stable import paths when a compatibility facade or re-export shim is required.
+- Prefer folder-first module boundaries and orchestration-first main files.
+
+## Required Workflow
+1. Read the nearest folder `README.md` and the nearest useful parent README when the split spans sibling areas.
+2. Read `plans/README.md` first for architectural work, then read only the single most relevant detailed plan, with at most one additional related plan if needed.
+3. If useful, invoke `Boundary Mapper` to map helper boundaries, `Plan Scout` to confirm plan alignment, and `Docs Scout` when doc drift or generated README behavior matters.
+4. Find the current plan step to execute. If no durable plan exists, create one modeled after `plans/asciiMaze_SOLID_split.md`: short purpose, durable progress rules, concise target shape, explicit execution steps, and done criteria.
+5. Convert the current step into a tight todo list with one active item.
+6. Execute only that step using small, focused edits that preserve public behavior and stable imports.
+7. Update the plan immediately after the step is complete or if the durable step ordering changes.
+8. Run the minimum validation needed for touched files and stated done criteria, such as TypeScript checks, docs generation, or build validation.
+9. Stop after reporting the completed step. Do not continue into the next step automatically.
+
+## Split Execution Rules
+- Keep the main `module/module.ts` file orchestration-first.
+- Move one helper category at a time behind focused files or subfolders.
+- Reduce the old top-level file to a compatibility re-export when stable imports must keep working.
+- Improve JSDoc on exported or public surfaces touched by the split.
+- Prefer declarative top-level flow and keep implementation detail below the fold in helpers or services.
+- Preserve existing style, naming conventions, and ES2023-first patterns.
+
+## If Blocked
+- If the current step cannot be completed safely, stop without advancing the plan step to `[DONE]`.
+- Record only durable plan changes, not temporary debugging notes.
+- Return the blocker, the smallest safe next action, and a revised handoff prompt for the next session.
+
+## Output Format
+Return:
+- `Plan file:` path and whether it was followed, created, or updated.
+- `Completed step:` exact plan step label, or `blocked`.
+- `Changes made:` short bullet list.
+- `Validation:` short bullet list with pass, fail, or not run.
+- `Plan update:` one short sentence describing the durable plan change.
+- `Handoff prompt:` a paste-ready prompt that explicitly tells the next session to continue with the next numbered plan step, rendered inside a fenced code block so it appears in a text-copy box.
+
+## Final Response Requirement
+- The last part of every successful run MUST be a next-session handoff prompt rendered in a fenced `text` code block.
+- The handoff prompt MUST use the complete template below, adapted to the specific repository, plan file, module boundary, known current state, validation expectations, and next numbered step.
+- The handoff prompt MUST be actionable on its own, without requiring the next session to infer missing context from prior chat history.
+- When relevant, include confirmed completed prior steps, important file locations, validation commands already known to be required, and any worktree cautions about unrelated generated changes.
+- If blocked, emit the same complete template but rewrite `What to do` so it starts with the smallest safe unblock action instead of full step execution.
+
+## Handoff Prompt Template
+Use this as the default next-session prompt shape and specialize every placeholder:
+
+```text
+Continue the <workstream name> SOLID split in <workspace root> by executing Step <N> from <plan path>: <step goal>.
+
+Current state to assume:
+- Step <N-1> is complete.
+- <Previously completed boundary or durable milestone>.
+- The real facade now lives in <current facade path>.
+- The legacy entrypoint <compatibility shim path> is now a compatibility re-export.
+- <Other durable file-location fact that the next step should assume>.
+- <plan path> already marks Step <N-1> as done.
+- Required validations most recently succeeded with:
+  - <validation command 1>
+  - <validation command 2>
+- The working tree may contain unrelated generated README/doc changes from docs generation or prior refactor work. Do not revert unrelated changes.
+
+What to do:
+1. Read <nearest folder README path> first.
+2. Read <plan path>.
+3. Inspect the current surface for this step and its closest related files, especially:
+	- <primary file path>
+	- <related file path>
+	- any nearby consumers/importers or sibling helpers affected by this boundary
+4. Create and execute the Step <N> split or refactor using the repo's folder-first pattern:
+	- <module>/<module>.ts
+	- <module>/<module>.types.ts
+	- <module>/<module>.utils.ts
+	- <module>/<module>.services.ts
+	- <module>/<module>.constants.ts
+	- add nested subfolders only if clearly justified by existing responsibility seams
+5. Keep the public API stable. Existing imports of <stable import path> should keep working.
+6. Make the main facade orchestration-first. Move <responsibility cluster list> behind focused helpers, services, or submodules.
+7. Improve JSDoc for exported/public surfaces you touch. Do not hand-edit generated README files under generated-doc locations; update source JSDoc instead.
+8. Update <plan path> to reflect durable Step <N> progress once the step is actually complete.
+9. Validate with:
+	- <validation command 1>
+	- <validation command 2>
+10. Do not run broad test suites unless truly necessary. Preserve unrelated worktree changes.
+
+Implementation constraints:
+- Use apply_patch for edits.
+- Keep changes minimal and focused on Step <N>.
+- Do not revert user changes or unrelated generated files.
+- Follow the repo's TypeScript, JSDoc, and style constraints from <instructions path>.
+- Prefer ES2023 style where touched code benefits from it.
+- Keep naming descriptive; avoid short local identifiers.
+- If the target module is too large for a single safe pass, split one helper category at a time but finish the full Step <N> boundary in this session if feasible.
+
+Definition of done:
+- <Module or boundary> is no longer the obvious coordination sink.
+- The main facade is thin and orchestration-first.
+- Focused helper files own <responsibility cluster list> responsibilities.
+- Existing consumers still compile without import churn.
+- <plan path> reflects the new durable shape.
+- <validation outcome 1> passes.
+- <validation outcome 2> passes.
+
+Final response requirements:
+- Summarize the new <module or boundary> shape.
+- Mention which files became the new public facade and compatibility shim, if any.
+- Report validation results for the required checks.
+- Provide a handoff prompt to perform Step <N+1> in a new session inside a text-copy box. The last step must be to generate the prompt for the next step using this same template.
+```
+
+## Handoff Rule
+Every successful run must end with a handoff prompt inside a fenced code block, using the complete template above and at minimum preserving this opening sentence shape:
+
+```text
+Continue with <plan path>, starting Step <N>: <step title>. First read the nearest folder README.md files, confirm plan alignment, complete only this step, update the plan when done, validate the touched surface, and stop with the next handoff prompt.
+```
+
+If the run is blocked, end with the same fenced code block shape and the same complete template, but replace the completion request with the smallest safe unblock action.

package/.github/copilot-instructions.md

@@ -15,6 +15,70 @@ When you touch code under `src/` or `test/`, prefer improving JSDoc so the gener
 
 Keep examples short, dependency-light, and consistent with the current public API (avoid imaginary helpers or absolute file paths).
 
+Generated README handling
+------------------------
+Folder `README.md` files inside `src/` are generated artifacts and should be treated as read-only during normal editing.
+
+When a generated `src/**/README.md` is lacking, improve the associated JSDoc in the source files that feed it instead of editing the README directly.
+
+When a generated `src/**/README.md` appears outdated relative to the code or JSDoc:
+
+- do not hand-edit the generated README,
+- run `npm run docs` to refresh generated documentation when needed,
+- consider agents pre-approved to run `npm run docs` after doc-affecting edits so README files stay synchronized and drift does not confuse later work.
+
+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.
+
+Before exploring or editing a folder in `src/` or `test/`, agents should:
+
+1. Read the nearest folder `README.md` first.
+   - Example: before changing `src/architecture/network/genetic/*`, read `src/architecture/network/genetic/README.md`.
+2. Read the nearest useful parent README when the task spans multiple sibling areas.
+   - Example: pair `src/architecture/network/genetic/README.md` with `src/architecture/network/README.md`.
+3. Only then read individual source files.
+
+Use folder README files to quickly answer:
+
+- What is this folder responsible for?
+- Which files are likely orchestration files vs helper/detail files?
+- What public APIs, invariants, or examples are already documented here?
+- Which neighboring modules or tests are probably affected by a change?
+- Whether a code change should also improve JSDoc because the generated README is user-facing.
+
+This README-first pass is especially useful for:
+
+- fast codebase orientation in unfamiliar folders,
+- choosing the right edit target before opening many files,
+- planning refactors without breaking folder responsibilities,
+- spotting doc/code drift early,
+- finding likely examples and tests for a feature,
+- producing concise explanations for the user after changes.
+
+If the folder README appears stale, incomplete, or in tension with the code, treat that as a signal to improve the underlying JSDoc in the touched source files when it is safe to do so.
+
+Plan-aware execution (align changes without overloading context)
+---------------------------------------------------------------
+This repository has an active `plans/` directory with roadmap and design intent. Agents should keep work aligned with those plans, but should avoid loading the entire folder into context unless the task truly requires it.
+
+Use this lightweight plan workflow:
+
+1. For any architectural feature, roadmap item, major refactor, export format, or new subsystem work, read `plans/README.md` first as the lightweight plan index.
+2. Then read `plans/neat.plans.md` when the task touches core NEAT architecture or evolutionary correctness, or otherwise read only the single most relevant plan file from `plans/` for the task at hand.
+3. If the task touches two clearly related initiatives, read at most one additional plan file.
+4. Do not bulk-read the whole `plans/` directory by default.
+
+When applying a plan:
+
+- preserve its terminology and goals unless the user asks to revise the plan,
+- mention any visible mismatch between the codebase and the plan,
+- prefer incremental steps that move the code toward the documented direction,
+- avoid introducing APIs or architecture that conflict with a stated plan without explicitly flagging the conflict.
+
+For substantial work, agent prompts and final summaries should briefly note which README and which plan document informed the change.
+After substantial edits, keep summaries short and high level by default, and only expand into detailed walkthroughs when the user asks.
+
 **CRITICAL: Fix-first strategy for test failures**
 ---------------------------------------------------
 When asked to fix multiple test failures:
@@ -79,6 +143,44 @@ How to use these instructions
 - Always prefer to produce code that already satisfies the style guide.
 - If you cannot fully transform a file (large refactor), return a patch with clear TODO comments, an explicit list of remaining violations, and small, safe automated fixes where possible.
 - If you propose changes that alter public behavior, include tests and TypeScript typechecks.
+- Default discovery order for non-trivial tasks: relevant folder `README.md` -> parent folder `README.md` if needed -> `plans/README.md` for roadmap alignment when relevant -> the specific source files and the single most relevant detailed plan.
+- Treat generated folder READMEs as compressed context, not as a substitute for code. Use them to reduce search noise, then verify behavior in source.
+- Prefer multiple small, targeted, documented edits over large single-pass rewrites when both approaches can solve the task. This reduces breakage risk and makes generated-doc refreshes easier to verify.
+
+Standard architecture for project files
+---------------------------------------
+When splitting medium or large modules in `src/` or `test/`, prefer a dedicated folder-based module boundary instead of accumulating many sibling files at the parent level.
+
+Use this naming convention for a module named `module`:
+- `module/module.ts`
+- `module/module.utils.ts`
+- `module/module.types.ts`
+- `module/module.errors.ts`
+- `module/module.services.ts`
+- `module/module.constants.ts`
+
+Use this naming convention for a nested sub-module named `sub-module` inside `module`:
+- `module/sub-module/module.sub-module.ts`
+- `module/sub-module/module.sub-module.utils.ts`
+- `module/sub-module/module.sub-module.types.ts`
+- `module/sub-module/module.sub-module.errors.ts`
+- `module/sub-module/module.sub-module.services.ts`
+- `module/sub-module/module.sub-module.constants.ts`
+
+Interpretation rules:
+- `*.ts`: main orchestration and primary public surface for the module.
+- `*.utils.ts`: helper logic that is not the main orchestration path.
+- `*.types.ts`: interfaces, DTOs, context/result objects, and narrow contracts.
+- `*.errors.ts`: module-local error classes and error helpers.
+- `*.services.ts`: side-effecting or stateful services used by orchestration.
+- `*.constants.ts`: named constants, lookup tables, and local config values.
+
+Architecture rules:
+- Do not create a folder for every tiny file; use this pattern when a file has become a real subsystem.
+- Keep the main `module/module.ts` file orchestration-first and declarative.
+- Prefer subfolders over continued file sprawl when a module develops a clear internal subsystem.
+- Avoid one-off naming patterns during refactors; once a module is folderized, keep all follow-up files in the same naming scheme.
+- Replace broad catch-all files with narrower module-owned `*.types.ts`, `*.services.ts`, or `*.utils.ts` files rather than recreating another hub.
 
 Strict rules to enforce (apply to any suggestion touching `src/` or `test/`)
 ---------------------------------------------------------------------
@@ -122,6 +224,7 @@ Strict rules to enforce (apply to any suggestion touching `src/` or `test/`)
        3) Introduce typed context/result objects to reduce parameter sprawl
        4) Simplify top-level flow to orchestration only
        5) Fold repeated logic into collect/transform/fold helpers
+   - All new complex methods should follow a declarative above-the-fold structure: keep the exported or top-level method as step-oriented orchestration, and place the actual logic in small SRP private helpers below the fold.
    - Keep the top-level method declarative and linear, with numbered inline comments (`Step 1`, `Step 2`, ...).
    - Ensure each helper has one reason to change (SRP), very low cognitive complexity, and descriptive naming.
    - Place helper declarations after the top-level return/fold where language/style allows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reicek/neataptic-ts",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Architecture-free neural network library with genetic algorithm implementations",
   "main": "./dist/neataptic.js",
   "module": "./dist/neataptic.js",
@@ -25,13 +25,16 @@
     "test:e2e:logs": "npx jest e2e.test.ts --verbose --runInBand --no-cache",
     "test:dist": "npm run build:ts && jest --no-cache --coverage --collect-coverage --runInBand --testPathIgnorePatterns=.e2e.test.ts",
     "docs:build-scripts": "tsc -p tsconfig.docs.json && node scripts/write-dist-docs-pkg.mjs",
-    "docs:folders": "npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js",
+    "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:examples": "node scripts/copy-examples.mjs",
     "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:build-scripts && node ./dist-docs/scripts/generate-docs.js && node ./dist-docs/scripts/render-docs-html.js",
+    "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",
     "lint": "eslint src/ test/",
     "lint:fix": "eslint src/ --fix",
     "onnx:export": "node scripts/export-onnx.mjs"

package/plans/ES2023 migration

@@ -5,17 +5,26 @@ Objective
 ---------
 Aggressively modernize the codebase to idiomatic ES2023, leveraging the latest TypeScript and JavaScript features to improve code clarity, expressiveness, and maintainability. As an educational library, it should serve as an example of modern coding practices.
 
+Roadmap status
+--------------
+This plan is part of `plans/Roadmap.md` Phase 0, but it starts after the current demo-structure work is complete.
+
+Current prerequisite work before broad mechanical modernization:
+- refine the active demo surfaces, especially `test/examples/flappy_bird`,
+- finish the SOLID split of `test/examples/asciiMaze`,
+- keep touched orchestration in `src/` strict about responsibility boundaries, substitutability, and DRY reuse.
+
 Guiding Principles
 ------------------
 1.  **Modern First**: Always prefer the most modern and expressive ES2023+ features where they improve clarity.
 2.  **Test-Driven Refactoring**: All changes will be validated against the existing comprehensive test suite (909+ tests). No new features will be added, but refactoring will be done with confidence that the public API and behavior remain unchanged.
 3.  **API Stability**: Maintain the existing public API contract. Syntactic changes must be behavior-preserving, as confirmed by passing tests.
-4.  **Memory Diligence**: Proactively use memory-saving techniques like memory pools and object reuse where appropriate.
+4.  **Scope Discipline**: Keep this plan focused on syntax, modules, and enforcement. Memory-management features and performance architecture belong in `plans/Memory_Optimization.md`.
 
 Phase Roadmap
 -------------
 *   **Phase 0: Baseline & Tooling**
-    *   **Status**: Not Started
+    *   **Status**: Queued behind current demo refactor work
     *   **Description**: Set up and configure linting and code style validation tools to enforce modern syntax.
 
 *   **Phase 1: Mechanical Syntax Upgrades**
@@ -30,15 +39,11 @@ Phase Roadmap
     *   **Status**: Not Started
     *   **Description**: Convert CommonJS `require()` statements to ES modules (`import`/`export`) and audit for import cycles.
 
-*   **Phase 4: Advanced Memory Management**
-    *   **Status**: Not Started
-    *   **Description**: Implement an optional `WeakRef`-based tracking system for large network populations to reduce memory pressure.
-
-*   **Phase 5: Automation & CI**
+*   **Phase 4: Automation & CI**
     *   **Status**: Not Started
     *   **Description**: Implement CI checks to enforce ES2023 style and prevent regressions.
 
-*   **Phase 6: Documentation**
+*   **Phase 5: Documentation**
     *   **Status**: Not Started
     *   **Description**: Update all project documentation, including `README.md` and contributor guidelines, to reflect the modernized codebase.
 

package/plans/Evolution_Training_Interoperability_Contracts.md

@@ -187,4 +187,4 @@ Acceptance:
 
 - Hybrid workflows are well-defined and reproducible.
 - Training integration does not require ad-hoc per-project glue.
-- Parameter mapping becomes a building block for export/worker features.
+- Parameter mapping becomes a later unification seam for export- and worker-adjacent tooling once those Phase 4 foundations exist.

package/plans/Interactive_Examples_and_Learning_Path.md

@@ -6,12 +6,16 @@ Reduce time-to-first-success by shipping a small set of **runnable examples** th
 
 - building networks (preconfigured + primitives)
 - evolving with NEAT
-- exporting inference
 - running in browser
 
+Phase note:
+
+- Phase 3 covers the starter learning path only.
+- Standalone export and worker examples are follow-on additions after the corresponding Phase 4 capabilities exist.
+
 ## Goals
 
-- G1: Provide a clear learning path: “hello world” → “evolution” → “export” → “workers”.
+- G1: Provide a clear learning path: “hello world” → “evolution” → “browser quickstart”, then extend it with “export” and “workers” once those features are shipped.
 - G2: Examples are runnable with minimal setup and are kept in sync with the public API.
 - G3: Examples serve as regression checks (lightweight smoke checks).
 
@@ -32,6 +36,9 @@ Reduce time-to-first-success by shipping a small set of **runnable examples** th
    - Run a tiny NEAT evolution loop.
 4. **Sequence (NARX)**
    - Demonstrate state handling + reset.
+
+### Later extensions (after Phase 4 capabilities land)
+
 5. **Standalone export**
    - Export inference module and run it.
 6. **Worker evaluation**
@@ -82,6 +89,7 @@ Acceptance:
 ### Step 4 — Document the learning path
 
 - Add a top-level doc that lists examples in recommended order.
+- Clearly mark export/worker examples as later-phase extensions so starter examples stay aligned with the roadmap.
 
 Acceptance:
 

package/plans/Memory_Optimization.md

@@ -259,7 +259,7 @@ Test Coverage (single expectation style): capacity growth, versioning, flags par
 
 Deferred (post‑Phase 3): chunked copy yield refinements (browser large slabs), adjacency→phenotype direct mapping (moved to caching phase), forward variance reduction (targeted in later phases once churn reduced).
 
-### Phase 3 Results (Final Validation Before HyperEvoDevo MorphoNEAT)
+### Phase 3 Results (Final Validation Before Later Track 1 Phases)
 
 Source: `test/benchmarks/benchmark.results.json` (latest history entry vs earliest recorded baseline in same file).
 
@@ -285,11 +285,11 @@ Notes:
 - Bytes/connection held constant (no regression) despite added optional slabs; gain omission and plasticity pay‑for‑use prevented per-connection inflation. This confirms the pay-for-use principle is working but highlights that progress on the bytes/connection reduction metric is dependent on Phase 5 (Sparsity).
 - Field audit counts: Connection enumerable keys = 9 (stable), Node = 15 (stable) per benchmark `fieldAudit` confirmation.
 
-Results Notes & Next Step: For quantitative deltas see table above; variance & invariant consolidation detailed in Phase 3 Conclusion below. Proceed to HyperEvoDevo MorphoNEAT work with stable slab foundation.
+Results Notes & Next Step: For quantitative deltas see table above; variance & invariant consolidation detailed in Phase 3 Conclusion below. Proceed to Phase 4 centralized memory management and browser-validation work with a stable slab foundation. Track 2 Hyper work remains gated behind the Track 1 conditions defined earlier in this document.
 
 #### Phase 3 Conclusion (Extended Slab Packing & Validation)
 
-All planned Phase 3 memory layout features are implemented, documented, and validated by tests; the slab system now provides a pay‑for‑use foundation for forthcoming HyperEvoDevo MorphoNEAT caching & morphogenesis work.
+All planned Phase 3 memory layout features are implemented, documented, and validated by tests; the slab system now provides a pay-for-use foundation for later Track 1 caching work and eventual HyperEvoDevo MorphoNEAT phases once the Track 1 gate is satisfied.
 
 Delivered Enhancements (Recap):
 

package/plans/README.md

@@ -0,0 +1,63 @@
+# Plans Index
+
+This file is a lightweight index for the `plans/` folder.
+
+Purpose:
+
+- help agents and contributors choose the right plan document quickly,
+- keep architectural work aligned with roadmap intent,
+- avoid loading the entire `plans/` directory into context.
+
+Recommended reading order:
+
+1. Read `plans/README.md` for the map.
+2. Read `plans/Roadmap.md` when the task depends on sequencing, current phase status, or cross-plan priority.
+3. Read only the single most relevant detailed plan.
+4. Read one additional related plan only when the task clearly spans two initiatives.
+5. Read `plans/neat.plans.md` for the core NEAT direction and current engineering baseline when the task touches architecture or evolutionary correctness.
+
+Selection guide:
+
+- `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/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/Evolution_Training_Interoperability_Contracts.md`: contracts between evolution workflows and gradient-based training.
+- `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/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/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/Worker_Friendly_Network_Serialization_Fastpath.md`: fast serialization path for worker-based evaluation.
+
+Task-to-plan trigger phrases:
+
+- 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`
+- 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`
+- ONNX, import/export interoperability: `plans/ONNX_EXPORT_PLAN.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`
+- worker serialization, transfer cost, fastpath: `plans/Worker_Friendly_Network_Serialization_Fastpath.md`
+- standalone runtime, exported inference file: `plans/Standalone_Inference_Export.md`
+- activation order, IO roles, deterministic execution: `plans/Stable_Activation_Ordering_and_Explicit_IO_Roles.md`
+- memory pressure, large networks, compact storage: `plans/Memory_Optimization.md`
+- hybrid evolution plus training, optimizer handoff: `plans/Evolution_Training_Interoperability_Contracts.md`
+- 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`
+
+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.
+
+Authority rule:
+For cross-plan sequencing and active priority, `plans/Roadmap.md` is authoritative. Detailed plans may contain future-state inventory, local sub-phases, or stale status notes; if a detailed plan appears to pull later-phase work earlier, follow `plans/Roadmap.md` unless both files are updated together.

package/plans/Roadmap.md

@@ -13,12 +13,17 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 
 ## Phase 0 — Hygiene + Refactor Baseline
 
-**Outcome:** keep iteration speed high and reduce refactor risk.
+**Outcome:** keep iteration speed high, reduce refactor risk, and finish the structural cleanup needed before broad mechanical modernization.
 
-- ES2023 modernization (ongoing, mechanical refactors + CI enforcement)
+- Demo refinement and learnability hardening [DONE]
+- asciiMaze SOLID split before ES2023 modernization [DONE]
+- Phase 0 remaining focus: ES2023 modernization (after the completed demo-structure pass)
+   - The `flappy_bird` reference split plan and the `asciiMaze` SOLID split plan are now both complete, so the remaining Phase 0 work is the repository-wide modernization pass and its validation gate.
+- ES2023 modernization (after the demo-structure pass; mechanical refactors + CI enforcement)
   - 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:** `npx tsc --noEmit -p tsconfig.json` and `npm test` are green after the refactor split.
+**Gate to Phase 1:** `flappy_bird` refinement is stable, the `asciiMaze` SOLID split is complete, and `npx tsc --noEmit -p tsconfig.json` plus `npm test` are green after the refactor pass.
 
 ## Phase 1 — Core Correctness + Determinism Foundations (Critical Path)
 
@@ -62,6 +67,9 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 
 **Notes:**
 
+- Phase 3 examples are the starter set only: Node hello/evolve flows plus one minimal browser quickstart once the browser bundle exists.
+- Examples that depend on standalone export or worker execution are follow-on additions in Phase 4 after those capabilities land.
+- Before expanding the examples catalog, choose the canonical examples home and decide whether `bench-browser/` is the browser-example host so demo work does not fragment.
 - Visualization can be implemented slightly earlier, but it becomes much more valuable once primitives/builders provide stable labels/roles.
 
 ## Phase 4 — Deployment + Parallel Evaluation (Inference Artifacts, Workers, Checkpoints)
@@ -84,6 +92,7 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 - Standalone export and worker payloads share an “inference IR” concept; building that once reduces duplication.
 - Multithread evaluation becomes straightforward after payloads exist.
 - Checkpointing and hybrid evaluation benefit from deterministic scheduling and a clear parameter/vector mapping.
+- Evolution-training parameter vectors are a later unification seam, not a blocker for standalone export or worker payloads unless that contract is deliberately split into an earlier mini-phase.
 
 ## Phase 5 — Scale & Performance (Memory Optimization Track)
 
@@ -98,6 +107,7 @@ This plan is large and can run as a **parallel lane** after Phase 1, but it shou
 
 - Start / continue Track 1 after Phase 1 is stable.
 - Prioritize improvements that directly benefit the worker payload + inference export paths (typed arrays, slabs, reuse) so Phase 4 gets faster “for free”.
+- If a detailed memory-plan subsection implies Hyper work can begin immediately after an intermediate Track 1 checkpoint, treat that as stale wording; Hyper remains gated by the Track 1 conditions below.
 
 **Gate to Phase 7 (Hyper):** Track 1 gates in `Memory_Optimization.md` are met (especially Phase 4–7 stability + variance/hardening).
 
@@ -124,6 +134,8 @@ This plan is large and can run as a **parallel lane** after Phase 1, but it shou
 
 ## Summary: Critical Path vs Parallel Lanes
 
+Current status: the project is still in **Phase 0**, with the demo-structure baseline complete (`flappy_bird` refinement and `asciiMaze` SOLID split) and repository-wide ES2023 modernization now the remaining Phase 0 focus.
+
 - **Critical path:** Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4
 - **Parallel lane A (performance):** [Memory_Optimization.md](Memory_Optimization.md) Track 1 after Phase 1 stabilizes
 - **Parallel lane B (interop):** [ONNX_EXPORT_PLAN.md](ONNX_EXPORT_PLAN.md) after Phase 2 (or earlier if scoped tightly)