@reicek/neataptic-ts 0.1.22 → 0.1.23

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

@@ -13,12 +13,14 @@ Your job is to map folder responsibilities, identify orchestration files versus
 - 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.
+- For demo/example tasks, DO NOT map only the demo boundary when the public library API or runtime contract is the real seam that should change.
 
 ## 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.
+3. Identify whether the triggering issue is truly demo-local or whether the demo is surfacing a reusable library DX gap.
+4. Identify the public API surface, orchestration file, helper clusters, tests, and likely affected neighbors.
+5. Return a stepwise decomposition that favors small, documented, low-risk passes.
 
 ## Output Format
 Return:

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

@@ -13,12 +13,14 @@ Your job is to identify the smallest useful subset of `plans/` documents for a t
 - 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.
+- For demo or example work, DO NOT default to demo-local compensation when the symptom points to a library/API/defaults gap; call out the higher-leverage library fix explicitly.
 
 ## 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.
+4. For demo-driven tasks, determine whether the demo is exposing a reusable library ergonomics gap and prefer plan alignment that fixes the library rather than the demo symptom.
+5. Extract terminology, constraints, sequencing hints, and any likely code/plan mismatch risks.
 
 ## Output Format
 Return:

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

@@ -1,5 +1,5 @@
 ---
-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."
+description: "Use when executing a deliberate SOLID module split, folderizing a large file, starting from a user-specified root such as #file:flappy_bird, following or creating a durable split plan, improving JSDoc so generated README files read naturally, 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, generated README, JSDoc, 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."
@@ -10,6 +10,8 @@ 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.
 
+You should follow the companion skill `solid-split-playbook` when it is available. Treat that skill as the canonical repository workflow for README-first reconnaissance, plan discipline, documentation upgrades, validation expectations, and final handoff quality.
+
 ## 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.
@@ -19,6 +21,7 @@ Your job is to complete one durable split step at a time, keep the codebase alig
 - 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 improve touched public JSDoc so generated README output becomes richer, more educational, and easier to navigate after the split.
 - 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.
 
@@ -29,15 +32,17 @@ Your job is to complete one durable split step at a time, keep the codebase alig
 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.
+7. Treat generated README files as doc-gap detectors. If the README would read too thinly after the split, improve the touched source JSDoc before validating.
+8. Update the plan immediately after the step is complete or if the durable step ordering changes.
+9. Run the minimum validation needed for touched files and stated done criteria, such as TypeScript checks, docs generation, or build validation.
+10. 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.
+- When a concept is important to understanding the boundary, prefer richer educational JSDoc that explains the why and, when useful, points readers toward a high-value background reference such as a relevant Wikipedia topic.
 - 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.
 

package/.github/copilot-instructions.md

@@ -76,6 +76,22 @@ When applying a 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.
 
+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:
+
+- treat the demo as evidence of a library DX gap first,
+- prefer fixing the library, public API, defaults, or shared runtime semantics,
+- use demo-local compensation only when the issue is genuinely demo-specific or a library fix would be unsafe for the current task,
+- if a temporary demo-local workaround is unavoidable, call it out explicitly as technical debt and note the preferred library-level fix.
+
+Critical expectation for feed-forward examples:
+
+- if a user selects a feed-forward builder or feed-forward mutation policy, agents should assume the expected DX is that feed-forward intent flows through to the runtime without extra demo-specific flags unless the codebase explicitly documents a different contract,
+- when that expectation is not met, agents should frame the issue as a library-level design gap and update plans accordingly.
+
 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.
 

package/.github/skills/solid-split-playbook/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: solid-split-playbook
+description: 'Plan and execute repo-consistent SOLID splits in NeatapticTS across src/ or test/, starting from a user-specified root such as #file:flappy_bird. Use when folderizing a module, thinning a compatibility facade, improving JSDoc so generated README files read naturally, or continuing an incremental split pass with stable imports.'
+argument-hint: 'Describe the split root, target module or folder, any relevant plan file, and optional detail about the next boundary to extract.'
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Solid Split Playbook
+
+Use this skill to run the NeatapticTS house style for deliberate, resumable,
+documentation-aware SOLID splits in either library code under `src/` or demos
+and examples under `test/`.
+
+This skill is designed to complement the existing `solid-split` custom agent.
+The skill defines the repository-specific split protocol, documentation bar,
+plan expectations, and validation checklist that should remain consistent across
+split sessions.
+
+## When to Use
+
+- The user wants a SOLID split, folderization pass, or orchestration-first
+  cleanup from a specific root such as `#file:flappy_bird`.
+- A top-level file is acting as a coordination sink and should become a thin
+  compatibility facade or stable public entrypoint.
+- A module boundary needs to be mapped before extracting `*.services.ts`,
+  `*.utils.ts`, `*.types.ts`, `*.errors.ts`, or `*.constants.ts` helpers.
+- Generated folder README output looks stale, thin, or not educational enough
+  after a refactor.
+- A multi-session split needs a durable plan, strict step sequencing, and a
+  high-quality handoff prompt for the next session.
+
+## Invocation Pattern
+
+Typical use:
+
+```text
+/solid-split
+SOLID split #file:flappy_bird
+```
+
+Useful optional detail to include:
+
+- the root from which to start splitting,
+- the current file or boundary believed to be overloaded,
+- the plan file to follow if one already exists,
+- whether this session should map boundaries, create the plan, or complete one
+  specific split step.
+
+## Primary Resources
+
+- [Split workflow checklist](./assets/split-workflow-checklist.md)
+- [Split plan template](./assets/split-plan-template.md)
+- [Documentation improvement checklist](./assets/docs-checklist.md)
+- Existing split execution agent: `solid-split`
+
+## Repo Discovery Order
+
+For any non-trivial split, follow this order before editing:
+
+1. Build a full README inventory for the requested root, including nested
+  subfolder `README.md` files that shape the documentation surface.
+2. Convert that README inventory into an explicit todo list so the session can
+  proceed folder by folder with visible scope.
+3. Read the nearest folder `README.md` for the target root.
+4. Read the nearest useful parent `README.md` if the split spans sibling
+  surfaces.
+5. Read `plans/README.md`.
+6. Read only the single most relevant detailed plan, plus at most one adjacent
+  plan if the split clearly spans two initiatives.
+7. Then inspect the smallest set of source files needed to confirm the actual
+  seams.
+
+Generated folder README files are reconnaissance artifacts. Do not hand-edit
+them. Use them to infer responsibility boundaries, missing docs, stale public
+surface descriptions, likely neighboring consumers, and where source JSDoc must
+improve.
+
+For documentation-heavy passes over a root such as `#file:flappy_bird`, the
+README inventory is mandatory. Do not start editing source until the full set of
+README-owning folders is visible in the todo list.
+
+## Split Philosophy
+
+The project prefers small, durable, orchestration-first refactors over large
+one-pass rewrites.
+
+- Keep stable public import paths working unless the user explicitly approves a
+  breaking change.
+- Reduce the old top-level file to a compatibility facade or public orchestration
+  surface when stable imports matter.
+- Move one responsibility cluster at a time into focused helpers or subfolders.
+- Prefer folder-based boundaries when a file has become a real subsystem.
+- Keep top-level flows declarative: collect, transform, fold, return.
+- Use descriptive names and ES2023-first style where the touched code benefits.
+
+For demos under `test/examples/`, treat DX gaps as library/runtime evidence
+first. Do not normalize demo-specific workarounds if the real issue is a shared
+API, default, or runtime contract.
+
+## Required Split Workflow
+
+1. Confirm the split root and whether the user wants planning, execution, or
+   continuation of an existing pass.
+2. Build a full inventory of every `README.md` under that root.
+3. Convert the inventory into a todo list that names each README-owning folder.
+4. Read the README files in that inventory before deep code search, starting at
+  the root and then proceeding folder by folder.
+5. Read `plans/README.md`, then the single most relevant plan file when the work
+   is architectural or part of an ongoing roadmap stream.
+6. If the split spans an unfamiliar area, use the existing `Boundary Mapper`,
+   `Plan Scout`, or `Docs Scout` agents as needed.
+7. If no durable plan exists, create one using the bundled template.
+8. Keep the README todo explicit and folder-focused, with exactly one active
+  README or folder documentation item at a time.
+9. Execute only one durable step unless the user explicitly asks for more.
+10. Improve JSDoc on touched exported and public surfaces so generated README
+   output remains educational, example-driven, and conceptually clear.
+11. Run the minimum validation needed for touched files and the step's done
+   criteria.
+12. Update the plan immediately after the step completes.
+13. End with a next-session handoff prompt that can continue from the next step
+   without depending on prior chat history.
+
+## Documentation Standards
+
+This repository is a public-facing educational library. Splits must improve the
+generated documentation story, not only the file structure.
+
+When touching exported or public surfaces:
+
+- Add or improve JSDoc so the generated README reads naturally.
+- Include concise “what/why” explanations, not only type signatures.
+- Add short `@example` blocks when behavior or intended usage is not obvious.
+- Mention invariants, defaults, performance costs, or error semantics when they
+  materially affect downstream users.
+- When the topic is conceptually important, suggest useful background reading in
+  plain prose inside the JSDoc description, for example a Wikipedia article on
+  a concept such as parallax, graph theory, dynamic programming, or NEAT.
+- Keep examples short, dependency-light, and aligned with the actual public API.
+
+Use the generated README as a doc gap detector:
+
+- If the README sounds too terse, improve source JSDoc.
+- If neighboring modules are undocumented in the README, consider whether the
+  touched source needs clearer exported comments.
+- If a new subfolder is introduced, run `npm run docs` after doc-affecting edits
+  so the generated README surface stays synchronized.
+- During large documentation passes, work through the README inventory one todo
+  item at a time instead of jumping between folders opportunistically.
+
+## Naming and File-Shape Rules
+
+Use the repo's standard architecture pattern where it fits the boundary:
+
+- `module/module.ts`
+- `module/module.utils.ts`
+- `module/module.types.ts`
+- `module/module.errors.ts`
+- `module/module.services.ts`
+- `module/module.constants.ts`
+
+For nested boundaries:
+
+- `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`: public surface or orchestration-first entrypoint.
+- `*.utils.ts`: pure or narrow helper logic.
+- `*.services.ts`: stateful, coordinating, or side-effecting helpers.
+- `*.types.ts`: typed contracts and context/result objects.
+- `*.errors.ts`: local error classes and error helpers.
+- `*.constants.ts`: named constants and local lookup tables.
+
+## Validation Rules
+
+After a split step, run only the minimum validation needed for the touched
+surface and the plan step done criteria.
+
+Typical options:
+
+- file-level diagnostics for touched files,
+- focused Jest tests for the changed surface,
+- `npx tsc --noEmit -p tsconfig.json` or `tsconfig.test.json` when the step is
+  type-heavy,
+- `npm run docs` after doc-affecting changes,
+- targeted build validation when the split changes bundling or runtime entry
+  behavior.
+
+Do not run broad test suites unless they are truly needed for the current step.
+
+## Guardrails
+
+- Do not hand-edit generated README files.
+- Do not revert unrelated user or generated changes.
+- Do not complete multiple durable plan steps in one invocation unless the user
+  explicitly asks.
+- Do not break stable import paths when a facade or compatibility shim is
+  appropriate.
+- Do not leave a plan stale after reshaping a step.
+- Do not treat examples as the final place to hide library ergonomics gaps.
+- Do not lower the documentation bar during refactors; public-facing docs should
+  get better as boundaries improve.
+
+## Expected Final Output
+
+The final response for a split step should include:
+
+- the plan file used or created,
+- the completed step label,
+- a short summary of the new boundary shape,
+- validation results,
+- the durable plan update,
+- a fenced `text` handoff prompt for the next step.

package/.github/skills/solid-split-playbook/assets/docs-checklist.md

@@ -0,0 +1,34 @@
+# Documentation Checklist For Splits
+
+Use this checklist whenever a split touches exported or public code.
+
+## Required
+
+- Every touched exported function, class, type, and shared constant has JSDoc.
+- JSDoc explains what the API does and why the boundary exists.
+- Parameters and returns are documented.
+- Non-obvious semantics include a short example.
+- Important invariants, defaults, error cases, or performance notes are called
+  out.
+
+## README-Aware Review
+
+Ask these questions while looking at the generated folder README:
+
+1. Would a first-time reader understand the purpose of the new subfolder?
+2. Does the public facade description explain why it still exists?
+3. Are helper files described in a way that sounds educational rather than
+   merely mechanical?
+4. Are any exported constants under-documented in the README because their
+   source JSDoc is too terse?
+5. Does the README make the module feel easier to explore after the split?
+
+## Educational Quality Bar
+
+- Prefer short conceptual descriptions over bare type restatement.
+- Use brief examples that match the current public API.
+- When the concept is central to understanding the design, mention useful
+  external reading in prose, such as a relevant Wikipedia article.
+- Keep examples and explanations dependency-light so they survive doc
+  generation cleanly.
+- Avoid filler comments that say only what the code already states.

package/.github/skills/solid-split-playbook/assets/split-plan-template.md

@@ -0,0 +1,48 @@
+# <Workstream Name> SOLID Split
+
+## Purpose
+
+Describe the coordination sink being reduced, the stable surface that must keep
+working, and the target architectural shape after the split.
+
+## Root
+
+- Split root: `<path>`
+- Nearest README reviewed: `<path>`
+- Parent README reviewed: `<path or n/a>`
+- Relevant plan: `<path or n/a>`
+
+## Durable Rules
+
+- Keep exactly one active step at a time.
+- Update this plan immediately after each completed step.
+- Preserve stable imports unless a breaking change is explicitly approved.
+- Do not hand-edit generated README files; improve source JSDoc and run docs.
+- Keep the true public facade orchestration-first.
+
+## Target Shape
+
+- `<facade path>` remains the public facade or compatibility shim.
+- `<subfolder path>` owns extracted helper categories.
+- Public responsibilities remain visible in the facade.
+- Implementation detail moves behind focused `*.services.ts`, `*.utils.ts`,
+  `*.types.ts`, `*.errors.ts`, or `*.constants.ts` files.
+
+## Steps
+
+- [] Step 1: Map the current boundary, stable imports, and likely helper seams.
+- [] Step 2: Extract the first focused responsibility cluster behind the stable
+  facade.
+- [] Step 3: Extract the next responsibility cluster and reduce the facade to
+  orchestration-only behavior.
+- [] Step 4: Improve JSDoc so the generated README reads naturally for the new
+  boundary.
+- [] Step 5: Validate the touched surface and record the durable boundary note.
+
+## Done Criteria
+
+- The target file is no longer the obvious coordination sink.
+- The public facade remains stable and orchestration-first.
+- Extracted helper files own the detailed responsibilities.
+- Generated README output reflects the new shape after docs regeneration.
+- The boundary can be resumed safely in a later session from this plan alone.

package/.github/skills/solid-split-playbook/assets/split-workflow-checklist.md

@@ -0,0 +1,51 @@
+# Split Workflow Checklist
+
+Use this checklist during each SOLID split session.
+
+## Before Editing
+
+1. Confirm the split root and the single durable step for this session.
+2. Build a full inventory of every `README.md` under the requested root.
+3. Convert that inventory into an explicit todo list so every README-owning
+   folder is visible before edits begin.
+4. Read the nearest folder `README.md` first.
+5. Read the nearest useful parent `README.md` if the boundary spans sibling
+   areas.
+6. Read `plans/README.md`.
+7. Read only the most relevant plan file, with at most one additional related
+   plan if needed.
+8. Inspect the current public surface, its closest helpers, and its main
+   consumers.
+9. Decide whether the current file should remain a public facade, a
+   compatibility shim, or the true orchestration entrypoint.
+
+## During the Split
+
+1. Keep exactly one active todo item.
+2. For documentation-heavy passes, keep that active item bound to one README or
+   one README-owning folder at a time.
+3. Move one responsibility cluster at a time.
+4. Prefer a dedicated subfolder when the file is a real subsystem.
+5. Keep the main entrypoint orchestration-first.
+6. Preserve stable imports where possible.
+7. Improve JSDoc on touched public surfaces while splitting.
+8. Add narrow tests only when they increase confidence in the extracted
+   boundary.
+
+## Documentation Pass
+
+1. Re-read the generated README mentally through the source JSDoc you touched.
+2. Add conceptual “what/why” text where the README would otherwise be too dry.
+3. Add short examples for exported APIs with non-obvious behavior.
+4. Mention defaults, invariants, error cases, and performance notes when they
+   matter.
+5. Suggest high-value background reading in JSDoc prose for important concepts
+   when that would help users learn from the API.
+
+## Validation
+
+1. Run file diagnostics for touched files.
+2. Run focused tests if the extracted logic has meaningful behavior to lock in.
+3. Run `npm run docs` when JSDoc or folder shape changed.
+4. Update the plan immediately after the step is complete.
+5. Stop and produce the next-session handoff prompt.

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

@@ -0,0 +1,63 @@
+---
+name: trace-analyzer-extension
+description: 'Extend scripts/analyze-trace.ts with new rollups, comparisons, script attribution, percentiles, or deterministic report sections. Use when the existing trace analyzer cannot answer an engineering question about Chrome trace or Perfetto data.'
+argument-hint: 'Describe the trace question, missing metric, and validation trace file.'
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Trace Analyzer Extension
+
+Use this skill when an agent needs to modify `scripts/analyze-trace.ts` instead
+of only consuming its current output.
+
+## When to Use
+
+- The existing analyzer output is not enough to explain a performance problem.
+- A trace audit needs a new deterministic rollup or comparison section.
+- A hotspot needs better attribution by bundle, worker URL, thread, or event.
+- The report needs percentiles, top-N comparisons, or a tighter summary format.
+- A one-off shell command would be too fragile or too noisy to repeat.
+
+## Primary Resources
+
+- [Analyzer extension workflow](./references/analyzer-extension-workflow.md)
+- [Extension checklist](./assets/extension-checklist.md)
+
+## Standard Workflow
+
+1. State the engineering question the current analyzer cannot answer.
+2. Read `scripts/analyze-trace.ts` before proposing a new section.
+3. Prefer extending existing helpers over adding parallel ad hoc logic.
+4. Keep output deterministic, text-first, and easy to compare across captures.
+5. Validate the new output against a real trace file from the repo.
+6. If the new section changes how agents should interpret results, update the
+   reporting skill or its reference docs too.
+
+## Output Design Rules
+
+- New sections must answer a concrete engineering question.
+- Prefer compact tables or one-line summaries over verbose prose.
+- Keep ordering deterministic by value, then stable by name when needed.
+- Preserve thread awareness so renderer, worker, browser, and GPU work remain
+  separable.
+- Avoid sections that require manual post-processing to become useful.
+
+## Guardrails
+
+- Do not add output that duplicates an existing section with minor formatting
+  changes.
+- Do not overfit the analyzer to one trace unless the repo clearly needs that
+  exact workflow.
+- Do not add non-deterministic timestamps, colors, or formatting noise.
+- Do not pull in a new dependency unless the existing TypeScript runtime cannot
+  reasonably support the change.
+- Keep JSDoc current when adding helpers or changing CLI behavior.
+
+## Repo-Specific Notes
+
+- The analyzer is intentionally lightweight and runs through `ts-node`.
+- The script already supports thread summaries, longest events, event rollups,
+  function-call attribution, and percentile summaries for selected events.
+- Extend the current architecture instead of replacing it with a large parser
+  abstraction unless the script has clearly outgrown the current shape.

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

@@ -0,0 +1,24 @@
+# Trace Analyzer Extension Checklist
+
+Use this checklist before finalizing changes to `scripts/analyze-trace.ts`.
+
+## Before Editing
+
+- Identify the exact engineering question.
+- Confirm the current analyzer cannot already answer it.
+- Pick the smallest extension type: rollup, attribution, or comparison.
+
+## During Editing
+
+- Keep the new logic deterministic.
+- Reuse existing helper patterns for duration conversion and thread labeling.
+- Add or update JSDoc for any new helper or CLI option.
+- Keep the report readable in a plain terminal.
+
+## Before Finalizing
+
+- Run the analyzer on a real repo trace.
+- Confirm the new section is actionable.
+- Confirm the new section does not duplicate older output.
+- Update the reporting skill if the default workflow changed.
+- Summarize the engineering value of the new section, not just the code change.

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

@@ -0,0 +1,101 @@
+# Analyzer Extension Workflow
+
+This reference explains how to safely extend `scripts/analyze-trace.ts` without
+turning it into a one-off debugging script.
+
+## Start With the Question
+
+Write the missing question in one sentence.
+
+Good examples:
+
+- Which thread owns most `HandlePostMessage` time?
+- Which script URLs dominate `FunctionCall` on dropped-frame traces?
+- Are frame spikes coming from a few outliers or a broad high-percentile shift?
+- How do two traces compare on dropped frames, worker totals, and hottest
+  events?
+
+If the question is vague, the output section will usually be vague too.
+
+## Preferred Extension Types
+
+Choose the smallest useful extension.
+
+### 1. New rollup section
+
+Use when the event exists already and only aggregation is missing.
+
+Examples:
+
+- event totals by thread,
+- `HandlePostMessage` by worker URL,
+- `RunTask` by thread category.
+
+### 2. Better attribution
+
+Use when a current section is correct but not actionable enough.
+
+Examples:
+
+- resolve script URL from event args,
+- surface worker URL alongside generic worker thread labels,
+- split browser-main and renderer-main owners more clearly.
+
+### 3. Comparison mode
+
+Use when engineers need baseline-versus-candidate reporting.
+
+Examples:
+
+- compare dropped frames between two traces,
+- compare top events and top threads side by side,
+- compare p50, p90, p99 frame metrics.
+
+Only add comparison mode if the repo is likely to reuse it.
+
+## Implementation Guidance
+
+Follow this order:
+
+1. Add or adjust the smallest data helper needed.
+2. Reuse existing normalization helpers for thread labels and durations.
+3. Keep the section printer near the existing report flow in `main()`.
+4. Preserve the current compact textual style.
+5. Add or update JSDoc for new helpers and CLI flags.
+
+## Validation Workflow
+
+Validate against a real trace from the repository.
+
+Recommended command pattern:
+
+```bash
+npm run trace:analyze -- <trace-path> --top=15
+```
+
+Validation questions:
+
+- Does the new section answer the intended question directly?
+- Is the output deterministic between runs?
+- Does the new section avoid duplicating older sections?
+- Does the script still work for a normal single-trace audit?
+
+## When to Update the Reporting Skill
+
+Update `.github/skills/trace-audit-reporting/` when the analyzer extension
+changes the default audit workflow.
+
+Examples:
+
+- a new high-value summary section should be mentioned in the workflow,
+- a new comparison mode becomes standard for regression triage,
+- a new CLI flag changes the recommended command.
+
+## Anti-Patterns
+
+- Adding raw JSON dumps.
+- Adding wide output that is hard to scan in chat or terminals.
+- Mixing data collection, formatting, and CLI parsing into one large helper.
+- Replacing deterministic summaries with subjective prose inside the script.
+- Adding a feature that only makes sense for one trace file with no reusable
+  value.