@zeix/cause-effect 0.18.5 → 1.0.1

package/skills/changelog-keeper/SKILL.md

@@ -1,59 +1,69 @@
 ---
-name: changelog
-description: Update CHANGELOG.md with user-facing changes. Use after meaningful code changes, when asked to add release notes, or to prepare a release.
+name: changelog-keeper
+description: >
+  Maintain CHANGELOG.md for the @zeix/cause-effect library. Use after meaningful code
+  changes, when asked to add release notes, or to prepare a release.
 user_invocable: true
 ---
 
-# Changelog Keeper
-
-Maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com) conventions.
-
-## Structure
+<objective>
+Maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com) conventions,
+adapted to this project's style: technically precise, developer-focused entries that include
+implementation detail when it explains *why* behavior changed or *how* to migrate.
+</objective>
 
+<structure>
 The changelog uses this heading hierarchy:
 
 ```markdown
 # Changelog
 
-## [Unreleased]
+## [Unreleased]        ← only present when unreleased changes exist
 
 ### Added
-### Changed
-### Deprecated
-### Removed
 ### Fixed
-### Security
 
-## 0.18.1
+## 1.0.0              ← released versions use bare version numbers, no brackets
 
-### Added
+### Changed
 ...
 ```
 
-- `## [Unreleased]` is always the first version section. New changes go here.
-- Only include categories that have entries.
-- Version 0.18.0 is the baseline. Do not document changes before it.
-
-## Adding entries
+- `## [Unreleased]` is only present when there are documented changes not yet released.
+  Create it at the top (below `# Changelog`) when documenting the first new change after a release.
+  It does not exist between releases.
+- Released versions use bare version numbers: `## 1.0.0`, `## 0.18.5`, etc. No brackets.
+- Only include category headings (`### Added`, `### Changed`, etc.) that have entries.
+- `## 0.18.0` is the baseline. Do not document changes before it.
+</structure>
 
+<adding_entries>
 1. Read `CHANGELOG.md`.
-2. Determine which changes are user-facing by inspecting the diff (`git diff main..HEAD -- src/ index.ts` or as directed).
-3. Classify each change into exactly one category: Added, Changed, Deprecated, Removed, Fixed, or Security.
-4. Write concise bullets describing user-visible behavior. Use backticks for public API names.
-5. Do not duplicate existing entries.
-6. Edit the file in place using the Edit tool.
-
-## Preparing a release
-
+2. Inspect the diff to identify changes: `git diff main..HEAD -- src/ index.ts` or as directed.
+3. If there is no `## [Unreleased]` section, create one immediately below `# Changelog`.
+4. Classify each change into exactly one category: Added, Changed, Deprecated, Removed, Fixed, or Security.
+5. Write entries following the style guide below.
+6. Do not duplicate existing entries.
+7. Edit the file in place using the Edit tool.
+</adding_entries>
+
+<preparing_a_release>
 When asked to release a version:
 
-1. Move all `[Unreleased]` entries under a new `## X.Y.Z` heading.
-2. Leave an empty `## [Unreleased]` section above it.
-3. Update `version` in `package.json` and the `@version` tag in `index.ts` to match.
-
-## Entry style
-
-- One behavior change per bullet.
-- Factual and concise; skip implementation-only details.
-- Include migration notes under Changed or Removed when behavior breaks compatibility.
-- Bold the API name or short summary at the start: `- **\`createMemo\` \`watched\` option**: description...`
+1. Rename `## [Unreleased]` to `## X.Y.Z` — do not leave an empty `[Unreleased]` section behind.
+2. Update `version` in `package.json` to match.
+3. Update the `@version` tag in `index.ts` to match.
+</preparing_a_release>
+
+<entry_style>
+- **One behavior change per bullet.**
+- **Bold the API name or short summary** at the start, followed by a colon:
+  `- **\`createMemo\` \`watched\` option**: description…`
+- **Include implementation details** when they explain *why* the behavior changed, *how* the
+  fix works, or *what internal invariant* is preserved. This changelog is read by developers
+  and AI agents integrating or contributing to the library — precision is expected.
+- **Use before/after framing for Fixed entries**: "Previously, X. Now, Y."
+- **Include migration notes** under Changed or Removed when behavior breaks compatibility.
+  State clearly what consumers must change and why.
+- Use backticks for all public API names, internal types, flags, and file names.
+</entry_style>

package/skills/tech-writer/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: tech-writer
+description: >
+  Keep developer-facing documents up to date with the @zeix/cause-effect source code:
+  README.md, GUIDE.md, ARCHITECTURE.md, REQUIREMENTS.md, CLAUDE.md,
+  .github/copilot-instructions.md, and JSDoc in src/. Use after code changes, to verify
+  consistency, or to update a specific document.
+user_invocable: true
+---
+
+<scope>
+This skill is for the cause-effect library repository. It expects source files at `src/`
+and `index.ts`, documentation at the project root, and agent instructions at `.github/`.
+
+For consumer projects using `@zeix/cause-effect` as a dependency, use the `cause-effect`
+skill instead.
+</scope>
+
+<essential_principles>
+**Read source before writing.** Always read the current state of the relevant source file(s)
+and the target document before making any changes. Never update from memory.
+
+**Tone adapts to audience.** Each document has a distinct primary reader and register.
+See references/tone-guide.md. Violating the tone is as wrong as a factual error.
+
+**Concise over comprehensive.** Every sentence must justify its presence. Cut anything
+that does not add information the reader needs. Technical accuracy is non-negotiable;
+length is not.
+
+**Surgical edits only.** Update what changed. Do not rewrite sections that are still
+accurate, and do not add commentary about what was updated.
+</essential_principles>
+
+<intake>
+What do you need to do?
+
+1. **Update after a code change** — `src/` or `index.ts` has changed and documents need
+   to reflect it
+2. **Review consistency** — check that all documents reflect the current source
+3. **Update a specific document** — you know exactly which one
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|---|---|
+| 1, "code changed", "after change", "just merged", "new feature", "bug fix" | workflows/update-after-change.md |
+| 2, "review", "consistency", "check", "audit", "verify" | workflows/consistency-review.md |
+| 3, "specific", or names a document | See document routing below |
+
+**Document-specific routing (option 3):**
+
+| Document named | Workflow |
+|---|---|
+| `README.md` or `GUIDE.md` | workflows/update-public-api.md |
+| `ARCHITECTURE.md` | workflows/update-architecture.md |
+| `CLAUDE.md` or `copilot-instructions.md` | workflows/update-agent-docs.md |
+| `REQUIREMENTS.md` | workflows/update-requirements.md |
+| JSDoc / `src/` | workflows/update-jsdoc.md |
+
+**Intent-based routing (clear intent without selecting a number):**
+- "document the new API" / "update README" → workflows/update-public-api.md
+- "update the architecture doc" → workflows/update-architecture.md
+- "update CLAUDE.md" / "add non-obvious behavior" → workflows/update-agent-docs.md
+- "update JSDoc" / "inline docs" → workflows/update-jsdoc.md
+- "update requirements" → workflows/update-requirements.md
+- "review all docs" / "check consistency" → workflows/consistency-review.md
+
+**After identifying the workflow, read it and follow it exactly.**
+</routing>
+
+<reference_index>
+All in `references/`:
+
+| File | Contents |
+|---|---|
+| document-map.md | Each document's audience, scope, update triggers, and consistency checks |
+| tone-guide.md | Writing tone, register, and conciseness rules per document type |
+</reference_index>
+
+<workflows_index>
+All in `workflows/`:
+
+| Workflow | Purpose |
+|---|---|
+| update-after-change.md | Determine which documents to update after a code change, then update them in order |
+| update-public-api.md | Update `README.md` and `GUIDE.md` |
+| update-architecture.md | Update `ARCHITECTURE.md` |
+| update-agent-docs.md | Update `CLAUDE.md` and `.github/copilot-instructions.md` |
+| update-requirements.md | Update `REQUIREMENTS.md` |
+| update-jsdoc.md | Update JSDoc comments in `src/` |
+| consistency-review.md | Review all documents for consistency with current source |
+</workflows_index>

package/skills/tech-writer/references/document-map.md

@@ -0,0 +1,199 @@
+<overview>
+Every document the tech-writer skill maintains, with its audience, scope, what triggers an
+update, and what to verify in a consistency review. Load this reference whenever you need
+to determine which documents are affected by a change.
+</overview>
+
+<documents>
+
+<REQUIREMENTS_md>
+**Path:** `REQUIREMENTS.md`
+**Audience:** Stakeholders, potential contributors, library authors evaluating adoption
+**Register:** Formal, strategic, timeless — written to survive version bumps
+**Scope:** Vision, primary and secondary audience, design principles, signal type set,
+runtime environments, bundle size targets, non-goals, stability guarantees
+
+**Update triggers:**
+- A signal type is added to or removed from the library
+- A runtime environment is added or dropped
+- A bundle size target changes
+- A design principle is added, changed, or removed
+- The primary or secondary audience shifts
+- A non-goal is resolved or a new one is established
+- Stability guarantees change (version milestone, compatibility stance)
+
+**Do NOT update for:** bug fixes, new options on existing types, internal refactors,
+documentation or tooling changes.
+
+**Consistency checks:**
+- Signal type count in prose ("9 signal types") matches the table row count
+- Signal type table rows match the exports in `index.ts`
+- Non-goals do not contradict any feature currently in the library
+- Runtime environments list reflects current CI targets
+</REQUIREMENTS_md>
+
+<README_md>
+**Path:** `README.md`
+**Audience:** Developers integrating the library — library authors and framework integrators
+**Register:** Instructional, example-driven, precise — assumes TypeScript competence
+**Scope:** Installation, quick start, full public API reference, signal type selection guide,
+advanced usage patterns (batching, cleanup, scopes, watched callbacks)
+
+**Update triggers:**
+- Any factory function is added, removed, or has a changed signature
+- Any option is added, renamed, removed, or changes semantics
+- Any exported type is added, removed, or renamed
+- A behavioral guarantee changes (e.g. sync vs async execution, equality semantics)
+- A new advanced usage pattern is added to the library
+
+**Consistency checks:**
+- Every factory function in `index.ts` has a `### SignalType` section under `## API`
+- All `@param`-level option names match current factory signatures
+- Code examples in the API sections use current factory signatures and compile
+- "Choosing the Right Signal" table covers all signal types with accurate descriptions
+- "Advanced Usage" examples use current API
+</README_md>
+
+<GUIDE_md>
+**Path:** `GUIDE.md`
+**Audience:** Developers migrating from React, Vue, or Angular
+**Register:** Comparative, educational, approachable — draws explicit parallels to other frameworks
+**Scope:** Conceptual mapping from React/Vue/Angular primitives, key behavioral differences
+(synchronous effects, auto-tracked dependencies, non-nullable types, scope-based ownership),
+and signal types that go beyond what standard frameworks provide
+
+**Update triggers:**
+- A core factory name changes (breaks the "Familiar Core" comparison table)
+- A fundamental behavioral contract changes — sync execution, dependency tracking model,
+  nullability rules, or ownership semantics
+- A new signal type is added that goes "Beyond the Basics"
+- An existing "Beyond the Basics" signal type changes significantly enough that a framework
+  developer's mental model derived from the guide would now be wrong
+
+**Do NOT update for:** new options on existing signal types, minor signature tweaks, internal
+changes, or anything that does not change how a React/Vue/Angular developer would think about
+the library.
+
+**Consistency checks:**
+- "The Familiar Core" table references current factory function names (`createState`,
+  `createMemo`, `createEffect`)
+- "What Works Differently" sections describe current behavior accurately
+- "Beyond the Basics" signal type sections use current factory signatures and options
+- Code examples compile against current `index.ts`
+</GUIDE_md>
+
+<ARCHITECTURE_md>
+**Path:** `ARCHITECTURE.md`
+**Audience:** Contributors to the library; AI agents reasoning about internals
+**Register:** Technical, precise, internal-facing — implementation details are expected and correct
+**Scope:** Graph engine data structures (edges, node field mixins, concrete node types),
+automatic dependency tracking (`activeSink`, `link`, `trimSources`, `unlink`), change
+propagation (flag semantics, `propagate`, `refresh`, `setState`), effect scheduling (`batch`,
+`flush`), ownership and cleanup (`activeOwner`, cleanup storage, `createScope`), and a
+per-signal-type subsection describing each type's internal composition and lifecycle
+
+**Update triggers:**
+- The `Edge` type fields change
+- Node field mixins (`SourceFields`, `SinkFields`, `OwnerFields`, `AsyncFields`) change
+- A concrete node type is added, removed, or its composition changes
+- `activeSink` or `activeOwner` semantics change
+- `link()`, `trimSources()`, or `unlink()` behavior changes
+- Flag names or values change (`FLAG_CLEAN`, `FLAG_CHECK`, `FLAG_DIRTY`, `FLAG_RUNNING`)
+- `propagate()`, `refresh()`, `setState()`, `batch()`, or `flush()` behavior changes
+- A new signal type is added (add a subsection) or removed (remove its subsection)
+
+**Consistency checks:**
+- "Concrete Node Types" table matches node shapes defined in `src/graph.ts`
+- "Node Field Mixins" table matches field groups in `src/graph.ts`
+- Flag names match constants in `src/graph.ts`
+- Each signal type subsection describes current internal composition and lifecycle
+- No subsection references a removed type, flag, or function
+</ARCHITECTURE_md>
+
+<CLAUDE_md>
+**Path:** `CLAUDE.md`
+**Audience:** Claude (this model) at inference time
+**Register:** Terse, direct, AI-optimized — every token has a cost; no explanatory padding
+**Scope:** Spreadsheet-cell mental model for all 9 signal types; internal node shapes and the
+`activeSink`/`activeOwner` dual-pointer model; non-obvious behaviors that a competent reactive
+developer would not predict from the public API alone
+
+**Update triggers:**
+- A signal type is added (extend the mental model list and node shapes)
+- Internal node shapes change (`src/graph.ts` field composition)
+- `activeSink` or `activeOwner` semantics change
+- A non-obvious behavior is introduced, changed, or resolved
+- An existing non-obvious behavior entry becomes inaccurate
+
+**Consistency checks:**
+- Mental model list covers all 9 signal types
+- Internal Node Shapes block matches `src/graph.ts`
+- `activeOwner`/`activeSink` description is accurate
+- Every non-obvious behavior entry is still correct for the current implementation
+- No entry describes behavior that has since changed or been removed
+</CLAUDE_md>
+
+<copilot_instructions_md>
+**Path:** `.github/copilot-instructions.md`
+**Audience:** GitHub Copilot during code generation
+**Register:** Structured, pattern-oriented — code examples are generation templates, not prose
+**Scope:** Project overview, core architecture summary (node types, edge structure, graph
+operations, flags), signal type descriptions with factory names, key file paths, coding
+conventions (TypeScript style, naming, error handling, performance patterns), API design
+principles, common code patterns (signal creation, reactivity, type safety, resource
+management), build system
+
+**Update triggers:**
+- A new signal type is added (add to signal types list, key files, and code patterns)
+- A factory function signature changes (update the corresponding code pattern)
+- A node type or flag is added, renamed, or removed (update Core Architecture section)
+- A new source file is added to `src/` (update Key Files Structure)
+- A coding convention or API design principle changes
+- A new common code pattern is established
+
+**Consistency checks:**
+- Signal Types list covers all 9 signal types with accurate factory name and one-line
+  description
+- Key Files Structure lists all current `src/` and `src/nodes/` files
+- Code patterns in "Common Code Patterns" use current factory signatures and option names —
+  verify each against `index.ts`
+- API Design Principles accurately describe current conventions
+- Core Architecture node types and flags match `src/graph.ts`
+</copilot_instructions_md>
+
+<jsdoc_in_src>
+**Path:** `src/nodes/*.ts`, `src/graph.ts`, `src/errors.ts`, `src/util.ts`, `src/signal.ts`
+**Audience:** IDE users (hover documentation), API consumers reading source
+**Register:** Brief, typed, precise — one-line summaries; `@param`/`@returns` only
+**Scope:** Public API functions and their parameters, return values, and non-obvious
+constraints. Internal helpers do not require JSDoc.
+
+**Update triggers:**
+- A public function's parameter is added, removed, renamed, or retyped
+- A public function's return value or semantics change
+- A public function is removed (remove its JSDoc block with it)
+
+**Consistency checks (spot-check):**
+- `@param` names match current parameter names in the function signature
+- `@returns` descriptions match current return type semantics
+- No `@param` tags reference removed parameters
+- No `@example` blocks use deprecated API
+</jsdoc_in_src>
+
+</documents>
+
+<change_to_document_matrix>
+Quick reference for update-after-change.md. Use this to identify affected documents.
+
+| Change type                        | JSDoc | ARCH | CLAUDE + copilot | README | GUIDE | REQ |
+|------------------------------------|-------|------|------------------|--------|-------|-----|
+| New signal type                    | ✓     | ✓    | ✓                | ✓      | ✓     | ✓ * |
+| Changed public signature / option  | ✓     | —    | ✓ if behavior    | ✓      | ✓ if mental model | — |
+| Removed public API                 | ✓     | ✓ if structural | ✓       | ✓      | ✓ if documented | — |
+| New / changed non-obvious behavior | —     | ✓ if graph-level | ✓      | ✓ if affects usage | — | — |
+| Internal implementation change     | —     | ✓    | ✓                | —      | —     | — |
+| Vision / scope / constraint change | —     | —    | —                | —      | —     | ✓ |
+
+\* For REQUIREMENTS.md: only the signal type table row. Not the prose count — update
+that to match automatically.
+</change_to_document_matrix>

package/skills/tech-writer/references/tone-guide.md

@@ -0,0 +1,189 @@
+<overview>
+Writing tone, register, and conciseness rules for each document maintained by the tech-writer
+skill. Violating the tone is as wrong as a factual error — each document has a distinct
+primary reader and serves a distinct purpose.
+</overview>
+
+<shared_rules>
+These rules apply to every document without exception:
+
+- **Concise over comprehensive.** Every sentence must add information the reader needs.
+  Cut throat-clearing, transitional padding, and restatements of what the code already
+  shows.
+- **Technically accurate over reassuring.** Do not soften edge cases, paper over
+  constraints, or omit behavior that is surprising but correct.
+- **No changelog language in documentation.** Documents state current truth. Never write
+  "previously", "as of version X", "we changed", or "now supports". Those belong in
+  CHANGELOG.md.
+- **No meta-commentary.** Do not write "This section explains…" or "See below for…".
+  Say the thing directly.
+- **Backtick all code.** Every API name, flag, file name, type name, option key, and
+  shell command is wrapped in backticks, even mid-sentence.
+</shared_rules>
+
+<README>
+**Primary audience:** Developers integrating `@zeix/cause-effect` into a project.
+They know TypeScript and have used reactive libraries before.
+
+**Register:** Instructional. Direct address ("use `createTask` when…"). Present tense.
+Active voice. Short sentences in prose; examples do the heavy lifting.
+
+**Structure rules:**
+- Each `### SignalType` section: one short paragraph describing what the signal is for,
+  then the signature, then options, then example(s). Description first — don't open with
+  the signature.
+- Options tables: one row per option. "Description" column is one line; if it needs more,
+  the option is complex enough to warrant a prose sentence below the table instead.
+- Examples: realistic, not trivial. Show actual usage patterns, not `const x = createState(0)`.
+  Prefer examples that demonstrate the signal's distinctive behavior.
+
+**What to cut:**
+- Explanations of TypeScript concepts the reader already knows
+- Warnings about things the type system already prevents
+- Motivational framing ("This is useful when you need to…")
+</README>
+
+<GUIDE>
+**Primary audience:** Developers migrating from React, Vue, or Angular who want to
+understand where this library's concepts map to — and diverge from — what they already know.
+
+**Register:** Comparative and educational. Assumes framework fluency; never assumes
+knowledge of this library. Uses "if you've used X, this is like Y, except…" framing.
+Approachable but never condescending.
+
+**Structure rules:**
+- Comparisons must be specific. Name the exact React hook, Vue function, or Angular
+  decorator being compared. Vague comparisons ("like in other frameworks") add no value.
+- Divergences get more space than similarities. The reader can infer the familiar parts;
+  the non-obvious differences are why this section exists.
+- Code examples: show both the framework equivalent and the cause-effect version side by
+  side when it aids comparison. Otherwise, cause-effect only.
+
+**What to cut:**
+- Explanations of how React/Vue/Angular work internally — assume the reader knows
+- Repetition of content already in README.md — GUIDE.md is conceptual, not a reference
+- Sections that say "this is the same as in other frameworks" without adding nuance
+</GUIDE>
+
+<ARCHITECTURE>
+**Primary audience:** Contributors to the library and AI agents that need to understand
+internals to implement or review changes correctly.
+
+**Register:** Technical and precise. Third person, present tense. Implementation details
+are expected and welcome. Internal function names, type names, flag names, and field names
+are used freely without definition — this document assumes the reader has the source open.
+
+**Structure rules:**
+- Describe mechanisms, not intentions. Not "this enables efficient updates" but "when
+  `propagate()` marks a node `FLAG_CHECK`, downstream nodes call `refresh()` before
+  deciding whether to recompute".
+- Pseudocode and inline type definitions are appropriate when they make a structure clearer
+  than prose would. Match the actual source types exactly — do not simplify.
+- Subsection depth: use the existing pattern (##, ###). Do not add new heading levels.
+
+**What to cut:**
+- Motivational framing ("The design optimizes for…") — state the mechanism, not the goal
+- Public API description — that belongs in README.md
+- Any sentence that could be replaced by reading the source directly
+</ARCHITECTURE>
+
+<CLAUDE_MD>
+**Primary audience:** Claude (this model) at inference time. Every token has a cost.
+
+**Register:** Terse, declarative, maximally dense. No hand-holding. No transitions.
+Bold key terms. Bullet lists over prose. Code examples only when the correct pattern is
+non-obvious from the statement.
+
+**Structure rules:**
+- Non-obvious behavior entries follow a strict three-part structure:
+  1. **Bold statement** of the behavior — one sentence, declarative, specific.
+  2. Implication or consequence — one or two sentences maximum.
+  3. Code example — only if the correct pattern cannot be inferred from the statement.
+     Use before/after style (bad comment + good comment) only when the contrast is the point.
+- The bar for "non-obvious": an experienced reactive developer would not predict this
+  behavior from the public API alone. If they would, it does not belong here.
+- Internal names (`FLAG_CHECK`, `activeSink`, `trimSources`) are appropriate — Claude
+  can cross-reference ARCHITECTURE.md.
+
+**What to cut:**
+- Any sentence that restates what the bold statement already said
+- Explanations of standard reactive concepts (memoization, lazy evaluation, dependency tracking)
+- "Note that…", "Keep in mind…", "Be aware that…" — state it directly
+- Examples that illustrate obvious correct usage; examples only for non-obvious patterns
+</CLAUDE_MD>
+
+<copilot_instructions>
+**Primary audience:** GitHub Copilot during code generation. The document drives what
+Copilot suggests as it completes function calls, option objects, and type annotations.
+
+**Register:** Structured and pattern-oriented. Headers create anchors Copilot uses to
+locate relevant context. Code blocks are generation templates — they must be complete,
+compilable, and idiomatic.
+
+**Structure rules:**
+- Code patterns must compile against the current `index.ts`. Copilot generates from these
+  literally — a wrong parameter name or stale option key will be reproduced in generated code.
+- Signal type descriptions: one line each in the format
+  `**Name** (\`createName\`): what it is and its key behavioral trait.`
+- Do not use narrative prose in list items — use fragments that complete a pattern, not
+  sentences that explain one.
+
+**What to cut:**
+- Explanatory prose around code patterns — the pattern is self-documenting
+- Options or parameters that are rarely used and not needed for the common case
+- Duplication between sections (e.g. do not describe `createTask` in both "Signal Types"
+  and again identically in "Common Code Patterns")
+</copilot_instructions>
+
+<REQUIREMENTS>
+**Primary audience:** Stakeholders, contributors, and future maintainers who need to
+understand the library's purpose and boundaries. This document is read infrequently and
+must remain accurate over many versions.
+
+**Register:** Formal, strategic, timeless. Third person. Noun phrases over verb phrases
+where possible ("The library is deliberately not a framework" rather than "We decided not
+to make this a framework"). No version-specific language except in "Stability".
+
+**Structure rules:**
+- Tables state facts as rows — they do not tell a story. Each row is self-contained.
+- "Non-Goals" entries are one bold heading + one sentence. The heading names the thing
+  that is out of scope; the sentence says why or what to do instead. No more.
+- "Stability" is the only section that may reference specific version numbers. All other
+  sections describe the library as it is, not how it got there.
+
+**What to cut:**
+- Rationale for decisions that were obvious or uncontroversial — if it needs defending,
+  add one sentence; otherwise state the fact
+- Historical context ("this was added because…")
+- Implementation detail — REQUIREMENTS.md describes goals, not mechanisms
+</REQUIREMENTS>
+
+<jsdoc>
+**Primary audience:** Developers reading function signatures in an IDE or in generated
+API documentation. They see the JSDoc in a tooltip or a docs page alongside the TypeScript
+signature.
+
+**Register:** Brief, typed, precise. One-line summaries. No narrative. Fragments are
+acceptable if they read naturally as a tooltip.
+
+**Structure rules:**
+- Summary line: one line. Describes what the function does, not what it is.
+  "Creates a mutable reactive signal." not "A factory function for State signals."
+- `@param` tags: one line each. Describe semantics and constraints, not the TypeScript
+  type (the type is already visible in the signature). For options objects, document only
+  options whose behavior is non-obvious.
+- `@returns`: one line. What is returned and any non-obvious guarantee
+  (e.g. "Always non-nullish per `T extends {}`").
+- `@throws`: only for errors that can occur in correct, non-erroneous usage. Do not
+  document programmer-error throws (`RequiredOwnerError`, `InvalidCallbackError`,
+  `CircularDependencyError`) — they indicate a coding mistake, not a handled condition.
+- `@example`: only if the usage pattern is so non-obvious that a developer would misuse
+  the function without it. Examples live primarily in README.md.
+
+**What to cut:**
+- `@param type` annotations — TypeScript already shows the type
+- JSDoc that restates the TypeScript signature in prose
+- Generic descriptions that would apply to any function ("Creates and returns a…")
+- Multi-paragraph descriptions — if it needs that much explanation, the API design may
+  need review
+</jsdoc>