@reicek/neataptic-ts 0.1.26 → 0.1.28

package/.github/copilot-instructions.md

@@ -1,15 +1,15 @@
 # Repo Copilot Instructions — NeatapticTS
 
-Purpose
--------
+## Purpose
+
 When generating, modifying, or suggesting code that touches files under `src/` or `test/`, follow the project `STYLEGUIDE.md` rules and perform the quick validations listed below before returning suggestions.
 
-Educational docs preference (JSDoc)
-----------------------------------
+## Educational docs preference (JSDoc)
+
 This is a public-facing, educational library. JSDoc comments are compiled into user-facing documentation (for example the aggregated READMEs under `src/**/README.md` generated by the docs workflow).
 
-Long-task logging and communication
------------------------------------
+## Long-task logging and communication
+
 For long-running or multi-pass work, keep user-facing chat minimal and prefer durable progress tracking in markdown files.
 
 Follow these rules:
@@ -20,53 +20,58 @@ Follow these rules:
 - Use `.plans.md` files for work in progress, pending decisions, next steps, and handoff context.
 - Use `.logs.md` files for completed work, concise pass history, and done-state records.
 - When creating or reshaping tracker files, use `tracker-handoff` as the canonical workflow for `[PLANNED]`, `[WIP]`, `[DONE]`, compression, and `Handoff query` structure.
+- When a workstream reaches `[DONE]`, the final tracker step is to compress the completed `.plans.md` into a short closed tracker and add or update a same-boundary `.logs.md` audit record.
+- Handoff prompts are strict for active trackers and blocker recovery, but omit them for fully closed trackers unless the user explicitly asks for reopen guidance.
 - When both chat and tracker files are available, treat the tracker files as the primary source of detailed continuity and keep chat as a thin status layer.
 
-Skill and companion-agent ownership model
------------------------------------------
+## Skill and companion-agent ownership model
+
 This repo now uses a skill-first customization model for durable workflow and
 policy.
 
 Use this boundary intentionally:
 
 - Skills own durable knowledge: workflow, standards, guardrails, tone models,
-   source-mapping rules, validation expectations, and handoff contracts.
+  source-mapping rules, validation expectations, and handoff contracts.
 - Companion agents stay thin and task-shaped. They gather evidence, map
-   boundaries, scout drift, or execute one narrow workflow step while deferring
-   durable policy to the relevant skill.
+  boundaries, scout drift, or execute one narrow workflow step while deferring
+  durable policy to the relevant skill.
 - When a skill and a companion agent overlap, update the agent to follow the
-   skill rather than copying the overlap forward.
+  skill rather than copying the overlap forward.
 - Prefer passing compact task packets and reconnaissance handoffs into skills
-   over re-stating full workflow rules in each agent.
+  over re-stating full workflow rules in each agent.
 
 Current intended ownership split:
 
 - `solid-split`: canonical split/refactor workflow and step sequencing.
 - `educational-docs`: canonical documentation quality workflow and generated
-   README/JSDoc policy.
+  README/JSDoc policy.
 - `test-fix-workflow`: canonical workflow for systematically repairing multiple
-   test failures.
+  test failures.
 - `plan-alignment`: canonical workflow for selecting and applying roadmap/plan
-   context.
+  context.
 - `tracker-handoff`: canonical workflow for `.plans.md` and `.logs.md`
-   structure, `[PLANNED]/[WIP]/[DONE]` status markers, compression, and
-   `Handoff query` continuity.
+  structure, `[PLANNED]/[WIP]/[DONE]` status markers, compression,
+  active-plan `Handoff query` continuity, and terminal closure into matching
+  `.logs.md` records.
 - `Boundary Mapper`: read-only seam mapping and structural handoff into
-   `solid-split`.
+  `solid-split`.
 - `Docs Scout`: read-only documentation reconnaissance and handoff into
-   `educational-docs`.
+  `educational-docs`.
 - `Plan Scout`: read-only roadmap reconnaissance and handoff into
-   `plan-alignment`.
+  `plan-alignment`.
 
 Use `educational-docs` by default when the task is primarily about documentation quality, generated README tone, source-mapped JSDoc improvement, Mermaid diagrams, citations, or Wikimedia-safe visuals.
 
 Use `tracker-handoff` by default when the task includes creating, compressing,
 or updating `.plans.md` or `.logs.md` files, especially when the tracker needs
-safe session continuation via a `Handoff query` section.
+safe session continuation via a `Handoff query` section or terminal closure via
+a compressed plan plus matching log.
 
 For split or refactor work with meaningful documentation scope, let `solid-split` own the boundary work and `educational-docs` own documentation quality.
 
 When you touch code under `src/` or `test/`, prefer improving JSDoc so the generated docs are:
+
 - **Interesting and explanatory**, not just type signatures.
 - **Example-driven**: include small examples in the main description (prefer fenced code blocks like ```ts) so the docs generator preserves them.
 - **Conceptual**: include a brief “what/why” explanation and any important semantics (defaults, invariants, error cases, performance notes).
@@ -79,8 +84,8 @@ Keep examples short, dependency-light, and consistent with the current public AP
 
 Keep this file focused on repo-level policy and invocation rules. The richer tone model, source mapping workflow, visual style guide, Mermaid diagram playbook, citation guidance, and Wikimedia Commons media rules belong in `educational-docs`.
 
-Generated README handling
-------------------------
+## 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.
@@ -91,8 +96,8 @@ When a generated `src/**/README.md` appears outdated relative to the code or JSD
 - run `npm run docs` to refresh generated documentation when needed,
 - consider `educational-docs` pre-approved to run `npm run docs` after doc-affecting edits so README files stay synchronized and drift does not confuse later work.
 
-CI-sensitive docs and tooling validation
----------------------------------------
+## CI-sensitive docs and tooling validation
+
 When a task touches `.github/workflows/**`, `package.json`, `package-lock.json`, `scripts/**` that launch docs or browser tooling, Mermaid rendering, Puppeteer/Chromium, or any dependency change that can affect those paths:
 
 - do not treat local Windows success as sufficient evidence for GitHub-hosted Linux runners,
@@ -100,8 +105,8 @@ When a task touches `.github/workflows/**`, `package.json`, `package-lock.json`,
 - run `npm run docs` when Mermaid, Puppeteer, docs generation, or related launch scripts are affected,
 - when browser-based docs tooling runs in Linux CI, explicitly account for Chromium sandbox restrictions and prefer durable script-level launch configuration over workflow-only ad hoc flags.
 
-Folder README reconnaissance (read this before deep code search)
----------------------------------------------------------------
+## 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:
@@ -118,8 +123,8 @@ If the folder README appears stale, incomplete, or in tension with the code, tre
 
 If the goal is to make that README materially more educational rather than merely less stale, invoke `educational-docs`.
 
-Plan-aware execution (align changes without overloading context)
----------------------------------------------------------------
+## Plan-aware execution (align changes without overloading context)
+
 This repository has an active `plans/` directory with roadmap and design intent.
 
 When a task touches architecture, roadmap items, major refactors, export
@@ -130,8 +135,8 @@ Keep this file as the invocation layer. The detailed plan-selection sequence,
 terminology preservation rules, bounded reading workflow, and mismatch handling
 belong in that skill.
 
-Demo-first library gap policy (critical)
----------------------------------------
+## Demo-first library gap policy (critical)
+
 Examples and demos in `test/examples/` are not places to normalize library ergonomics gaps. They are probes that should reveal where the public API, defaults, or runtime contracts fall short of world-class expectations.
 
 When demo work exposes a mismatch between obvious user intent and the library behavior:
@@ -149,60 +154,62 @@ Critical expectation for feed-forward examples:
 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.
 
-Multi-test failure workflow
----------------------------
+## Multi-test failure workflow
+
 When asked to fix multiple test failures, invoke `test-fix-workflow` instead of
 re-stating the repair protocol in ad hoc instructions.
 
 Keep this file as the invocation layer. The detailed planning sequence,
 validation cadence, and no-premature-test-run rules belong in that skill.
 
+## ES2023-first policy (strict)
 
-ES2023-first policy (strict)
-----------------------------
 For educational clarity and a modern look, always prefer idiomatic ES2023 syntax when it improves readability or safety without changing behavior. This repo is intentionally opinionated: use the immutable array methods and modern language constructs by default.
 
 Prefer (non-exhaustive):
+
 - Arrays: `toSorted`, `toReversed`, `toSpliced`, `with`, `.at(-1)`, `findLast`, `findLastIndex`.
 - Objects: spread/rest over `Object.assign` for shallow copies and merges.
 - Optional chaining `?.` and nullish coalescing `??` (avoid `||` for defaulting unless you mean falsy semantics).
 - Deep clone: `structuredClone` (or the project helper `safeStructuredClone` when cross-env safety is needed).
 - Errors: `Error` with `{ cause }` (e.g., `new Error(msg, { cause })`).
 - Numerics: numeric separators for long literals (for readability only, not to change values).
-- Modules: ES modules `import`/`export` over CommonJS `require`/`module.exports` (follow the repo’s phase plan; new code should be ESM). 
+- Modules: ES modules `import`/`export` over CommonJS `require`/`module.exports` (follow the repo’s phase plan; new code should be ESM).
 
 Avoid (legacy/less clear):
+
 - In-place `sort`, `reverse`, `splice` in code paths that expect immutability; use the ES2023 immutable variants above.
 - `Object.assign({}, obj)` or `Object.assign([], arr)` for cloning; use object/array spread.
 - `JSON.parse(JSON.stringify(x))` for deep clone; use `structuredClone`/`safeStructuredClone`.
 - Index math like `arr[arr.length - 1]`; prefer `arr.at(-1)` when readability benefits.
 - CommonJS `require()` in new or refactored modules; prefer ESM.
 
-How to use these instructions
------------------------------
+## 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.
 - Prefer invoking the relevant repo skill when the task matches an established
-   workflow instead of duplicating that workflow in ad hoc instructions.
+  workflow instead of duplicating that workflow in ad hoc instructions.
 - 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.
 - For documentation-first work, invoke `educational-docs` instead of duplicating its standards in ad hoc instructions.
 - For split work with meaningful docs scope, let `solid-split` own sequencing and `educational-docs` own documentation quality.
 - For multiple test-failure repair work, invoke `test-fix-workflow` instead of
-   duplicating its planning and validation sequence here.
+  duplicating its planning and validation sequence here.
 - For architectural or roadmap alignment work, invoke `plan-alignment` instead
-   of duplicating its bounded plan-reading workflow here.
+  of duplicating its bounded plan-reading workflow here.
 - For read-only reconnaissance before implementation, prefer companion agents
-    such as `Boundary Mapper`, `Docs Scout`, and `Plan Scout`, but keep them subordinate to the
-   relevant skill-owned workflow.
+  such as `Boundary Mapper`, `Docs Scout`, and `Plan Scout`, but keep them subordinate to the
+  relevant skill-owned workflow.
+
+## Standard architecture for project files
 
-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`
@@ -211,6 +218,7 @@ Use this naming convention for a module named `module`:
 - `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`
@@ -219,6 +227,7 @@ Use this naming convention for a nested sub-module named `sub-module` inside `mo
 - `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.
@@ -227,14 +236,15 @@ Interpretation rules:
 - `*.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/`)
----------------------------------------------------------------------
+## Strict rules to enforce (apply to any suggestion touching `src/` or `test/`)
+
 1. Naming: avoid short local identifiers. Do not use these short names for non-trivial locals: `dx`, `dy`, `d`, `i`, `a`, `b`, `c`, `p`, `o`, `cand`, `tries`, `idx`.
    - If the original code uses a short name in a tiny loop (1–3 lines) and it is clearly idiomatic, allow `i`, `j` only.
    - Prefer descriptive names: `candidateDirection`, `bestDistance`, `currentPosition`.
@@ -255,35 +265,36 @@ Strict rules to enforce (apply to any suggestion touching `src/` or `test/`)
 
 8. Local helper structure preference:
    - For new or refactored functions that introduce internal helpers, order the function as:
-       1) Local variables/constants at top
-       2) Declarative logic (calls to helpers)
-       3) Return (fold)
-       4) Internal helper function declarations at the end of the parent function
-    - Helpers should be small and pure where practical, with step-level inline comments and JSDoc.
+     1. Local variables/constants at top
+     2. Declarative logic (calls to helpers)
+     3. Return (fold)
+     4. Internal helper function declarations at the end of the parent function
+   - Helpers should be small and pure where practical, with step-level inline comments and JSDoc.
 
 9. Mandatory implementation pattern (always; keep cognitive complexity low):
    - Applies to all new code and any modified/refactored code in `src/` and `test/`.
-   - Prefer a *declarative top-level flow* ("collect → transform → fold/return") over deeply nested control flow.
+   - Prefer a _declarative top-level flow_ ("collect → transform → fold/return") over deeply nested control flow.
    - Avoid ternary chains (especially nested) for multi-branch fallback logic; use named resolver helpers with early returns instead.
    - When normalizing legacy/loose data, isolate type assertions/casting into a single helper and keep the rest strongly typed.
    - Keep helpers after the fold, and give each helper a single responsibility (SOLID: SRP). If the logic reads like a decision tree, it likely wants 2–4 small helpers.
 
 10. General multi-pass decomposition requirements (apply to all medium/large refactors):
-   - Perform refactors in explicit passes, in this order unless unsafe:
-       1) Stabilize current behavior and identify seams
-       2) Extract pure helpers by responsibility
-       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.
-   - Prefer immutable pass-style transforms (`map`, `filter`, `reduce`, index-collection helpers) over mixed mutation-heavy loops.
-   - When passing more than 3-4 arguments repeatedly, introduce a typed context object and shared result types.
-
-Example (ideal structure)
--------------------------
+
+- Perform refactors in explicit passes, in this order unless unsafe:
+  1.  Stabilize current behavior and identify seams
+  2.  Extract pure helpers by responsibility
+  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.
+- Prefer immutable pass-style transforms (`map`, `filter`, `reduce`, index-collection helpers) over mixed mutation-heavy loops.
+- When passing more than 3-4 arguments repeatedly, introduce a typed context object and shared result types.
+
+## Example (ideal structure)
+
 ```ts
 export function exampleMethod(input: Input) {
    const constants = /* ... */;
@@ -319,22 +330,21 @@ type Intermediate = unknown;
 type Output = unknown;
 ```
 
-Automated validations to run before finalizing a suggestion
--------------------------------------------------------
+## Automated validations to run before finalizing a suggestion
+
 When you modify or create files under `src/` or `test/`, run (or advise running) these quick validations. If you cannot run them, still make sure your suggestion would pass them.
 
-1) TypeScript diagnostics
+1. TypeScript diagnostics
 
    # Copilot instructions — STYLEGUIDE light checks
 
-   Purpose
-   -------
+   ## Purpose
+
    Give brief, actionable guidance so suggestions touching `src/` or `test/` prioritize compliance with `STYLEGUIDE.md`.
 
    Keep it light: prefer small, automated checks and a short validation summary with every patch.
 
-   Quick checks to run (recommended)
-   --------------------------------
+   ## Quick checks to run (recommended)
    - TypeScript: run `npm run build` and report pass/fail.
    - Clean install: when `package.json`, `package-lock.json`, or workflow/runtime tooling changes, run `npm ci` and report pass/fail.
    - Tests heuristic: flag test files that contain more than one `expect(` occurrence (these should be split into multiple `it()` blocks).
@@ -342,39 +352,41 @@ When you modify or create files under `src/` or `test/`, run (or advise running)
    - CI browser/docs tooling: when the changed path can invoke Mermaid, Puppeteer, or Chromium in CI, validate `npm run docs` and do not assume local non-Linux success generalizes to GitHub-hosted Linux.
    - ES2023 modernization: flag legacy patterns and suggest modern equivalents (see below one-liners).
 
-   PowerShell examples (local validation)
-   -------------------------------------
+   ## PowerShell examples (local validation)
+
    Typecheck:
+
    ```powershell
    npx tsc --noEmit -p tsconfig.json
    ```
 
-   What to include with a suggestion
-   --------------------------------
+   ## What to include with a suggestion
    - A short validation summary (TypeScript: pass/fail, short-id matches: list or 0, test-expect heuristic: list or 0, JSDoc missing: list or 0).
    - ES2023: list any flagged legacy patterns and the intended replacements (e.g., `Object.assign` -> spread, `arr[arr.length-1]` -> `arr.at(-1)`, `JSON.parse(JSON.stringify())` -> `structuredClone`).
    - If any issue can't be safely fixed automatically, include a TODO comment at the top of the changed file and a one-line explanation in the patch.
 
-   Test failure workflow
-   ---------------------
+   ## Test failure workflow
+
    When fixing multiple test failures, invoke `test-fix-workflow` for the
    detailed repair sequence.
 
+## Refactor format: large-file split (step-by-step, user-confirmed)
 
-Refactor format: large-file split (step-by-step, user-confirmed)
----------------------------------------------------------------
 When splitting a large module into submodules, invoke `solid-split` and let it
 own the detailed stepwise execution protocol, including user-confirmed
 stepwise mode when requested.
 
 Quality thresholds and investigation rules
------------------------------------------- 
+
+---
+
 - End every user facing response with `(Certainty: NN%)`
 - If your certainty is below 90%, stop and investigate before proceeding
 - If your certainty is below 95%, investigate further and ask follow-up questions until the requirements and environment are clear enough
 
-Low context window mitigation
------------------------------
+## Low context window mitigation
+
 When you need to make a change that requires more context than you have available:
+
 - Update the relevant source plan document with a NEXT: item describing the change and the reason for it, so that future work in that area has more context.
-- Provide a handoff prompt in a text-copy box with the relevant context and a clear question about how to proceed, so that a companion agent can pick it up and investigate.
+- Provide a handoff prompt in a text-copy box with the relevant context and a clear question about how to proceed, so that a companion agent can pick it up and investigate.

package/.github/skills/educational-docs/SKILL.md

@@ -38,6 +38,33 @@ rules, Mermaid policy, and citation/media guardrails. Companion agents such as
 gaps, and hand those specifics back into this skill rather than re-defining the
 documentation bar themselves.
 
+## Repo Preference Override
+
+When a generated README chapter is the target surface, treat the opening under
+the top `#` heading as the highest-leverage teaching surface in the repo.
+
+Hard requirements for that opening unless the user explicitly narrows scope:
+
+- optimize first for the first section because most readers will only read that
+  introduction before deciding whether to continue,
+- write the opening as an educational chapter introduction rather than as API
+  scaffolding or a symbol index,
+- keep the opening focused on the technical know-how behind the boundary named
+  by the title, for example `# neat/cache` should teach cache invalidation,
+  stale derived state, and why the boundary exists before it lists exports,
+- prefer roughly 5 to 10 short paragraphs in the opening when the boundary is a
+  meaningful educational surface,
+- prefer 2 to 3 Mermaid diagrams when they materially improve retention,
+- include at least 1 compact external reference when it helps teach the core
+  idea faster, with Wikipedia allowed as a background bridge,
+- include at least 2 small examples in the chapter when the public surface is
+  easier to understand through usage than through prose alone.
+
+Use these expectations as defaults for `src/**` educational chapter work. If a
+boundary is too small to sustain that much introduction without padding, keep
+the prose tight and explain in the final summary why a smaller opening was the
+better teaching choice.
+
 ## When to Use
 
 - A generated README feels technically correct but emotionally flat or hard to
@@ -257,9 +284,11 @@ See the visual rules in [Astro Bird visual style guide](./assets/visual-style-gu
 3. Read before rewriting.
    - Read the nearest folder README, then the nearest useful parent README.
    - Read the smallest set of source files that own the public story.
-  - Judge the README's flow like a chapter outline: opening promise, reading
-    order, conceptual bridges, and whether the symbol sequence helps or hurts
-    learning.
+
+- Judge the README's flow like a chapter outline: opening promise, reading
+  order, conceptual bridges, and whether the symbol sequence helps or hurts
+  learning.
+
 4. Define the reader questions.
    - What is this for?
    - Why is it shaped this way?
@@ -282,40 +311,47 @@ See the visual rules in [Astro Bird visual style guide](./assets/visual-style-gu
      prose with a properly attributed source.
    - Prefer one high-value reference over a noisy list.
 8. Evaluate Mermaid-first visuals deliberately.
-  - Prefer Mermaid Markdown for architecture overviews, data flows, decision
-    flows, state transitions, timelines, simple charts, and structural maps.
-  - When a chapter contains multiple policy modes, stages, or grouped option
-    families, assume at least one chart should probably exist unless the prose
-    is already unusually compact and obvious.
-  - Prefer adding a second chart when it answers a different reader question
-    than the first one, for example: one chart for execution flow and one chart
-    for mode comparison, taxonomy, or metric condensation.
-  - Treat GitHub README rendering as the primary Mermaid compatibility target
-    unless the task explicitly says the diagram only needs to work in the
-    generated HTML docs.
-  - Style diagrams with the Astro Bird palette so structure remains blue-led
-    and emphasis stays scarce.
-  - Add diagrams when they reduce confusion, not merely because Mermaid is
-    available.
-  - Choose the diagram family that matches the teaching goal.
-  - Validate non-trivial Mermaid syntax before finalizing when tooling is
-    available.
-  - Prefer conservative Mermaid syntax when the README itself is a primary
-    surface on GitHub.
+
+- Prefer Mermaid Markdown for architecture overviews, data flows, decision
+  flows, state transitions, timelines, simple charts, and structural maps.
+- When a chapter contains multiple policy modes, stages, or grouped option
+  families, assume at least one chart should probably exist unless the prose
+  is already unusually compact and obvious.
+- Prefer adding a second chart when it answers a different reader question
+  than the first one, for example: one chart for execution flow and one chart
+  for mode comparison, taxonomy, or metric condensation.
+- Treat GitHub README rendering as the primary Mermaid compatibility target
+  unless the task explicitly says the diagram only needs to work in the
+  generated HTML docs.
+- Style diagrams with the Astro Bird palette so structure remains blue-led
+  and emphasis stays scarce.
+- Add diagrams when they reduce confusion, not merely because Mermaid is
+  available.
+- Choose the diagram family that matches the teaching goal.
+- Validate non-trivial Mermaid syntax before finalizing when tooling is
+  available.
+- Prefer conservative Mermaid syntax when the README itself is a primary
+  surface on GitHub.
+
 9. Evaluate external visuals deliberately.
-  - Add images only when they improve understanding, not for decoration.
-  - Prefer Wikimedia Commons files with clear free-license metadata.
-  - Record author, source URL, license, and modification status.
+
+- Add images only when they improve understanding, not for decoration.
+- Prefer Wikimedia Commons files with clear free-license metadata.
+- Record author, source URL, license, and modification status.
+
 10. Regenerate and inspect.
-   - Run `npm run docs` after doc-affecting edits to generated surfaces.
-   - Re-read the generated output as if you were new to the module.
+
+- Run `npm run docs` after doc-affecting edits to generated surfaces.
+- Re-read the generated output as if you were new to the module.
+
 11. Tighten the experience.
-   - Remove repetition.
-   - Replace dry restatements with explanation.
-   - Make the reading order obvious.
-   - Keep README surfaces within a readable size whenever the boundary allows;
-    if the chapter still feels monolithic after normal source-first improvement,
-     escalate to `solid-split` instead of accepting an oversized folder README.
+
+- Remove repetition.
+- Replace dry restatements with explanation.
+- Make the reading order obvious.
+- Keep README surfaces within a readable size whenever the boundary allows;
+  if the chapter still feels monolithic after normal source-first improvement,
+  escalate to `solid-split` instead of accepting an oversized folder README.
 
 ## Post-Split Follow-Up Mode
 
@@ -326,10 +362,10 @@ mode:
 2. Preserve the split's new ownership story and make it easier to read.
 3. Prefer source-JSDoc improvements first when the README surface is generated.
 4. Add diagrams only when the new boundary is still hard to understand without
-  one.
+   one.
 5. Regenerate docs when the touched surface feeds generated README output.
 6. Report the doc pass as the follow-up to the completed split step so the
-  workflow remains legible.
+   workflow remains legible.
 
 This mode exists to keep the follow-up deterministic: every completed split
 gets a documentation polish pass, but that pass stays proportional to the code
@@ -346,6 +382,11 @@ For any document with a top-level `#` heading, the opening should read like the
 first pages of a chapter: define the problem space, explain why this boundary
 exists, and give the reader a clear path into the sections that follow.
 
+For this repo's chapter-style generated READMEs, the opening should usually be
+long enough to stand alone as the main learning surface. Assume that the opening
+is doing most of the educational work and that later symbol sections exist to
+support, not replace, that introduction.
+
 When the surface belongs to a neural-network subsystem, also answer the silent
 reader question behind most educational passes: "What does this let the network
 learn, preserve, or control that it otherwise could not?"
@@ -551,6 +592,11 @@ For diagram selection, syntax caveats, and validation guidance, use
 - When updating a running plan document after a completed pass, compress older
   completed entries to the essentials: keep `Goals`, `Progress`, optional
   `Achievements`, and `Decision`.
+- When a documentation workstream becomes fully complete, finish with
+  `tracker-handoff` terminal closure: compress the `.plans.md` file into a
+  short closed tracker and add or update the same-boundary `.logs.md` file.
+- Do not keep a `Handoff query` on a terminally closed plan unless the user
+  explicitly wants reopen guidance.
 - Remove `Validation` from completed passes after the result has been folded
   into `Progress` or `Decision`.
 - Keep `Remaining gaps` and `Next step` only on the active latest pass unless
@@ -588,17 +634,21 @@ When the task includes updating an in-repo plan log, the updated log should
 also leave only the active pass with forward-looking `Remaining gaps` and
 `Next step`; prior completed passes should stay compressed.
 
+When that in-repo plan reaches terminal closure, the final tracker action
+should be the compressed closed plan plus the matching `.logs.md` record rather
+than a next-session handoff prompt.
+
 ## Companion Agent Contract
 
 If a companion agent uses this skill, it should:
 
 1. Name this skill explicitly as `educational-docs`.
 2. Pass concrete reconnaissance findings into the skill instead of paraphrasing
-  them away.
+   them away.
 3. Keep the agent prompt focused on read-only discovery and gap reporting when
-  the agent is a scout.
+   the agent is a scout.
 4. Avoid restating the full workflow, tone model, or guardrails that already
-  live here.
+   live here.
 5. Recommend `solid-split` explicitly when reconnaissance shows the README is
-  too monolithic for a healthy docs-only pass.
+   too monolithic for a healthy docs-only pass.
 6. Update the agent when this skill changes materially so both remain aligned.