@zeix/cause-effect 1.0.0 → 1.0.2

package/skills/cause-effect/references/signal-types.md

@@ -0,0 +1,292 @@
+<overview>
+What each signal type in @zeix/cause-effect is for, when to use each one, and how to choose between similar types. All knowledge is embedded — no external files required.
+</overview>
+
+<signal_catalog>
+
+<State>
+**What it is:** A mutable reactive value you own and update explicitly.
+
+**Use when:**
+- You control when and how the value changes
+- The value is UI state, form input, a counter, a toggle, a selection
+- You need to write to it directly with `.set()`
+
+**Key facts:**
+- Requires an initial value
+- Synchronous reads and writes
+- Supports `equals` (default `===`) and `guard` options
+
+```typescript
+const count = createState(0)
+count.set(count.get() + 1)
+count.update(n => n + 1)   // if update helper exists; else use set
+```
+</State>
+
+<Sensor>
+**What it is:** A reactive value produced by an external source you don't control.
+
+**Use when:**
+- The value comes from outside the reactive graph: DOM events, timers, WebSocket messages, geolocation, device orientation, IntersectionObserver, etc.
+- You need `watched`/`unwatched` hooks to start and stop the external subscription efficiently
+- The value has no meaningful initial state before the source fires
+
+**Key facts:**
+- Starts **unset** — reading before the first value throws `UnsetSignalValueError`; use `match` to handle the initial state
+- `watched` fires when the first downstream effect subscribes; `unwatched` fires when the last one unsubscribes
+- The setup function receives a `set` callback; return a cleanup function to tear down the subscription
+
+```typescript
+const pointer = createSensor<{ x: number; y: number }>(set => {
+  const handler = (e: PointerEvent) => set({ x: e.clientX, y: e.clientY })
+  window.addEventListener('pointermove', handler)
+  return () => window.removeEventListener('pointermove', handler)
+})
+```
+</Sensor>
+
+<Memo>
+**What it is:** A synchronously derived value that stays in sync with its dependencies.
+
+**Use when:**
+- The value can be computed from other signals without async work
+- You want to avoid recomputing an expensive derivation on every read
+- You need a stable reference: Memo caches the last computed value and only recomputes when dependencies change
+
+**Key facts:**
+- Lazy — only recomputes when read after a dependency has changed
+- Receives `prev` as its first argument (enables referential stability patterns)
+- Supports `equals` to suppress downstream propagation when the new value is equivalent
+
+```typescript
+const fullName = createMemo(() => `${firstName.get()} ${lastName.get()}`)
+```
+</Memo>
+
+<Task>
+**What it is:** An asynchronously derived value — like Memo, but async.
+
+**Use when:**
+- The derivation requires `await` (data fetching, async transforms, indexed DB reads)
+- You want automatic cancellation of in-flight work when dependencies change
+
+**Key facts:**
+- Starts **unset** until the first async operation completes; use `match` for the loading state
+- Receives `(prev, signal: AbortSignal)` — always forward `signal` to `fetch` or any cancellable async operation to prevent stale responses overwriting fresh ones
+- Re-runs automatically when tracked dependencies change, aborting the previous run
+
+```typescript
+const results = createTask(async (prev, signal) => {
+  const res = await fetch(`/api/search?q=${query.get()}`, { signal })
+  return res.json()
+})
+```
+</Task>
+
+<Effect>
+**What it is:** A side effect that runs when its tracked dependencies change.
+
+**Use when:**
+- You need to synchronise reactive state with the outside world: update the DOM, write to localStorage, send analytics, call an imperative library
+- You need a reactive subscription that runs code (not just derives a value)
+
+**Key facts:**
+- **Must be created inside an owner** (`createScope` or another effect) — throws `RequiredOwnerError` otherwise
+- Runs immediately on creation, then re-runs on dependency changes
+- Returns a `Cleanup` function; calling it disposes the effect and all its children
+- Use `unown` inside `connectedCallback` / `disconnectedCallback` when the DOM manages the element's lifetime
+
+```typescript
+const dispose = createScope(() => {
+  createEffect(() => {
+    document.title = pageTitle.get()
+  })
+})
+// later: dispose()
+```
+</Effect>
+
+<Slot>
+**What it is:** A reactive property descriptor — a signal packaged as a getter/setter pair compatible with `Object.defineProperty`.
+
+**Use when:**
+- You need to attach a reactive value as a property on an object (e.g. a Web Component's observed attribute)
+- You want property access (`element.name`) to participate in the reactive graph
+
+**Key facts:**
+- Has `get`, `set`, `configurable`, and `enumerable` fields
+- Can be passed directly to `Object.defineProperty`
+- Backed by a `State` internally
+
+```typescript
+const nameSlot = createSlot(store, 'name')
+Object.defineProperty(element, 'name', nameSlot)
+```
+</Slot>
+
+<Store>
+**What it is:** A reactive object whose properties are individually reactive.
+
+**Use when:**
+- You have a group of related values that are read and updated independently
+- You want fine-grained reactivity on an object's fields rather than replacing the whole object
+
+**Key facts:**
+- Reading a property inside an effect creates a dependency on that property only
+- Updating one property does not re-run effects that only read other properties
+
+```typescript
+const user = createStore({ name: 'Alice', age: 30 })
+user.name = 'Bob'   // only effects reading `user.name` re-run
+```
+</Store>
+
+<List>
+**What it is:** An ordered, keyed reactive collection — an array where each item has a stable identity.
+
+**Use when:**
+- Order matters and items have identity (drag-and-drop lists, ranked results, timelines)
+- You need to react to structural changes (items added, removed, reordered) as well as value changes
+
+**Key facts:**
+- Items are identified by a stable key; keys survive sorting and reordering
+- `byKey()`, `at()`, `keyAt()`, and `indexOfKey()` are direct lookups — they **do not create graph edges**
+- To react to structural changes, read `get()`, `keys()`, or `length` instead
+- To update an existing item, use `list.replace(key, value)` — **not** `byKey(key).set(value)`. `replace()` propagates to all subscribers; `byKey().set()` silently misses effects that subscribed via `keys()`, `length`, or the iterator
+
+```typescript
+const todos = createList(
+  [{ id: 't1', text: 'Buy milk', done: false }],
+  { keyConfig: todo => todo.id }
+)
+todos.add({ id: 't2', text: 'Walk dog', done: false })
+todos.replace('t1', { id: 't1', text: 'Buy milk', done: true }) // update in place
+todos.remove('t2')
+```
+</List>
+
+<Collection>
+**What it is:** A keyed reactive collection — a reactive Map.
+
+**Use when:**
+- Items are identified by key and order is not meaningful or variable
+- You need fast key-based lookup with reactive tracking on the key set and individual entries
+- Use cases: entity caches, normalised data stores, lookup tables
+
+**Key facts:**
+- `createCollection` creates a collection from an initial set of entries
+- `deriveCollection` creates a collection derived from another reactive source
+- Same tracking rules as List: `byKey()` does not create graph edges; read `get()`, `keys()`, or `length` to subscribe to structural changes
+
+```typescript
+const users = createCollection<string, User>(
+  existingUsers.map(u => [u.id, u])
+)
+```
+</Collection>
+
+</signal_catalog>
+
+<decision_guide>
+
+<choose_by_value_source>
+**Who controls the value?**
+
+- You set it explicitly → **State**
+- An external event or subscription provides it → **Sensor**
+- It is computed from other signals (sync) → **Memo**
+- It is computed from other signals (async) → **Task**
+</choose_by_value_source>
+
+<choose_by_purpose>
+**What do you need to do with it?**
+
+- Read a derived value without side effects → **Memo** or **Task**
+- Run a side effect when something changes → **Effect**
+- Expose a reactive value as an object property → **Slot**
+- Group related reactive values on an object → **Store**
+- Maintain an ordered list of keyed items → **List**
+- Maintain an unordered map of keyed items → **Collection**
+</choose_by_purpose>
+
+<direct_comparisons>
+
+**State vs Sensor**
+Use `State` when you call `.set()` yourself. Use `Sensor` when an external source calls the setter — the library manages the subscription lifecycle via `watched`/`unwatched`.
+
+**Memo vs Task**
+Use `Memo` for synchronous derivations. Use `Task` when derivation requires `await`. Both receive `prev` and both support `equals`.
+
+**Memo vs Effect**
+`Memo` derives a value (no side effects, lazy). `Effect` runs side effects (imperative, eager, requires owner).
+
+**State vs Store**
+Use `State` for a single primitive or object that is always replaced wholesale. Use `Store` for an object whose individual properties are read and updated independently — Store gives you field-level reactivity.
+
+**List vs Collection**
+Both are keyed. Use `List` when order is significant (rendering order, ranking, sorting). Use `Collection` when items are looked up by key and order is not meaningful.
+
+**List / Collection vs Store**
+Use `Store` for a fixed set of named properties on a single object. Use `List` or `Collection` for a dynamic number of items with uniform shape.
+
+</direct_comparisons>
+
+</decision_guide>
+
+<common_patterns>
+
+<loading_state>
+Sensor and Task start unset. Use `match` to handle all states in one expression:
+
+```typescript
+createEffect(() => {
+  match([task], {
+    ok: ([data]) => renderData(data),
+    err: ([error]) => renderError(error),
+    nil: () => renderSpinner(),
+  })
+})
+```
+</loading_state>
+
+<grouping_effects>
+Always wrap top-level effects in `createScope` to control their lifetime:
+
+```typescript
+const dispose = createScope(() => {
+  createEffect(() => { /* ... */ })
+  createEffect(() => { /* ... */ })
+})
+
+// When done (e.g. component unmounted):
+dispose()
+```
+</grouping_effects>
+
+<coalescing_updates>
+Use `batch` when multiple state writes should trigger only one downstream propagation:
+
+```typescript
+batch(() => {
+  x.set(1)
+  y.set(2)
+  z.set(3)
+  // downstream effects run once, after all three are set
+})
+```
+</coalescing_updates>
+
+<reading_without_subscribing>
+Use `untrack` to read a signal's current value without creating a dependency edge:
+
+```typescript
+createEffect(() => {
+  const primary = primary.get()           // tracked — re-runs when primary changes
+  const snapshot = untrack(() => log.get()) // not tracked — just reads current value
+  console.log(primary, snapshot)
+})
+```
+</reading_without_subscribing>
+
+</common_patterns>

package/skills/cause-effect/workflows/answer-question.md

@@ -0,0 +1,54 @@
+<required_reading>
+Load references based on question type — only what is needed:
+
+- Which signal to use → references/signal-types.md
+- API usage, call signatures, options → references/api-facts.md
+- Unexpected or counterintuitive behavior → references/non-obvious-behaviors.md
+- A thrown error → references/error-classes.md
+- Design rationale or constraints → references/signal-types.md + references/api-facts.md
+</required_reading>
+
+<process>
+## Step 1: Categorise the question
+
+| Category | Signal words | Load |
+|---|---|---|
+| Which signal to use | "should I use", "difference between", "when to use", "State vs", "Memo vs" | signal-types.md |
+| API usage / call signature | "how do I", "what does X return", "what are the options for", "how to create" | api-facts.md |
+| Unexpected behavior | "why does this not work", "is this a bug", "why is watched not firing", "not re-running" | non-obvious-behaviors.md |
+| Error meaning | "what does X error mean", "when is Y thrown", "getting RequiredOwnerError" | error-classes.md |
+| Design rationale | "why was X designed this way", "why no null", "why is T extends {}" | signal-types.md + api-facts.md |
+
+## Step 2: Load only the relevant references
+
+Do not load all references speculatively. Load only the file(s) listed for the identified category.
+
+## Step 3: Answer from embedded knowledge
+
+All knowledge needed to answer public-API questions is in `references/`. Ground every claim in a reference. Cite the section when the answer is non-obvious (e.g. "per `non-obvious-behaviors.md`…").
+
+For counterintuitive behaviors, always show a correct vs incorrect code example alongside the explanation.
+
+## Step 4: When embedded knowledge is insufficient
+
+If the question requires detail beyond what the references cover (e.g. exact internal flag values, propagation algorithm specifics, architecture decisions), do not guess. Instead:
+- Point to the library's README and GUIDE in the npm package or GitHub repository for public API depth
+- Note that library internals are available in `node_modules/@zeix/cause-effect/src/` if truly needed, but internal details are not part of the public API contract and may change
+
+## Step 5: Design rationale questions
+
+When asked why the library was designed a certain way, distinguish between:
+- **Hard constraints** (e.g. `T extends {}` excludes null/undefined by design to guarantee signals always have a value; the signal type set is intentionally minimal and closed to new types)
+- **Soft conventions** (naming patterns, file organisation, option defaults)
+
+If the distinction is unclear from the embedded references, say so rather than speculating.
+</process>
+
+<success_criteria>
+- Answer is grounded in embedded reference knowledge
+- No references to external files that may not exist in the consumer project (REQUIREMENTS.md, ARCHITECTURE.md, src/, etc.)
+- Source cited when the answer is non-obvious
+- Counterintuitive behaviors include correct vs incorrect code examples
+- When knowledge is insufficient, points to upstream documentation rather than guessing
+- No reference files loaded beyond what the question required
+</success_criteria>

package/skills/cause-effect/workflows/debug.md

@@ -0,0 +1,71 @@
+<required_reading>
+1. references/non-obvious-behaviors.md — most reactive bugs are documented here
+2. references/error-classes.md — if a specific error is thrown
+3. references/api-facts.md — to verify the signal is being used correctly
+</required_reading>
+
+<process>
+## Step 1: Categorise the symptom
+
+Match the symptom to the most likely cause before reading any code:
+
+| Symptom | Most likely cause | Where to look |
+|---|---|---|
+| Effect doesn't re-run when a signal changes | No graph edge established (conditional read or direct lookup) | non-obvious-behaviors: `conditional-reads-delay-watched`, `direct-lookups-do-not-track` |
+| Effect re-runs too often | Missing `equals` option, or mutable reference without `SKIP_EQUALITY` | api-facts: `options.equals`, `SKIP_EQUALITY` |
+| `watched` never fires | Signal only read inside a conditional branch | non-obvious-behaviors: `conditional-reads-delay-watched` |
+| Collection/List update not reflected in effect | Using `byKey()`, `at()`, `keyAt()`, or `indexOfKey()` | non-obvious-behaviors: `direct-lookups-do-not-track` |
+| Stale async result overwrites fresh one | `AbortSignal` not forwarded to `fetch` or async operation | non-obvious-behaviors: `task-abort-on-dependency-change` |
+| `UnsetSignalValueError` thrown | Reading Sensor or Task before first value | non-obvious-behaviors: `sensor-unset-before-first-value` |
+| `RequiredOwnerError` thrown | `createEffect` called outside a `createScope` or parent effect | api-facts: `createEffect`, `createScope` |
+| `CircularDependencyError` thrown | A signal depends on itself, directly or transitively | error-classes: `CircularDependencyError` |
+| Downstream Memo or Effect never updates despite source changing | Custom `equals` on an intermediate Memo is suppressing the subgraph | non-obvious-behaviors: `equals-suppresses-subtrees` |
+| Cleanup not running / memory leak suspected | Effect created without an active owner, or `unown` used incorrectly | api-facts: `unown`, `createScope` |
+
+## Step 2: Read the relevant section
+
+Read the specific section in references/non-obvious-behaviors.md or references/error-classes.md that matches the symptom. Compare the pattern shown there to the code in question.
+
+## Step 3: Verify API usage
+
+If the symptom does not match a known gotcha, read references/api-facts.md to confirm:
+- Signal generics use `T extends {}` (no `null` or `undefined`)
+- `createEffect` is inside an owner (`createScope` or another effect)
+- `unown` is used only for DOM-owned lifecycles, not to bypass ownership generally
+- `batch` is used if multiple state writes should coalesce
+
+## Step 4: Inspect library source (last resort)
+
+If the embedded references do not explain the behavior, the library source is available at:
+
+```
+node_modules/@zeix/cause-effect/src/
+```
+
+Read the relevant file there — do **not** assume library source files exist at the project root.
+
+## Step 5: Fix
+
+Apply the minimal change that addresses the root cause. Do not suppress the symptom (e.g. wrapping a read in `untrack`) without first confirming that is the intended behavior.
+
+## Step 6: Verify
+
+Run the project's own test suite:
+
+```bash
+# use whichever applies to this project
+npm test
+pnpm test
+yarn test
+npx vitest
+npx jest
+```
+
+Do not assume `bun` or any specific test runner is available.
+</process>
+
+<success_criteria>
+- Root cause identified, not symptom suppressed
+- Fix matches the correct pattern from references/non-obvious-behaviors.md where applicable
+- Project test suite passes after the fix
+</success_criteria>

package/skills/cause-effect/workflows/use-api.md

@@ -0,0 +1,63 @@
+<required_reading>
+1. references/signal-types.md — choose the right signal type(s) for the task
+2. references/api-facts.md — correct API usage, constraints, and callback patterns
+3. references/non-obvious-behaviors.md — avoid common pitfalls before writing any code
+</required_reading>
+
+<process>
+## Step 1: Choose the right signal type
+
+Read references/signal-types.md. Match the task to the appropriate signal(s) using the decision guide. If multiple signal types seem applicable, the guide has explicit comparisons.
+
+## Step 2: Check ownership requirements
+
+Before writing any `createEffect` call, confirm there is an active owner in scope:
+- Top-level effects must be wrapped in `createScope`
+- Effects in Web Component lifecycle methods that use DOM-managed lifetime should use `unown`
+
+See references/api-facts.md → `<core_functions>` for the rules.
+
+## Step 3: Check for known pitfalls
+
+Skim references/non-obvious-behaviors.md for anything that applies to the task:
+
+| If the task involves… | Check… |
+|---|---|
+| List or Collection | direct-lookups-do-not-track |
+| Conditional rendering or `match` | conditional-reads-delay-watched |
+| Async data fetching | task-abort-on-dependency-change |
+| Sensor or Task before first value | sensor-unset-before-first-value |
+| Multiple state updates at once | references/api-facts.md → `batch` |
+
+## Step 4: Import what you need
+
+All public API is imported from the package root:
+
+```typescript
+import {
+  createState, createSensor, createMemo, createTask,
+  createEffect, createScope, createSlot, createStore,
+  createList, createCollection, deriveCollection,
+  batch, untrack, unown, match,
+  SKIP_EQUALITY,
+} from '@zeix/cause-effect'
+```
+
+Only import what the task requires.
+
+## Step 5: Implement
+
+Write the code following the patterns in references/. Prefer the examples shown there over inventing new patterns — the non-obvious behaviors exist precisely because intuitive patterns are often wrong.
+
+## Step 6: Verify
+
+Run the project's own test suite using whatever command applies to this project (e.g. `npm test`, `pnpm test`, `npx vitest`, `deno test`). Do not assume a specific test runner or package manager.
+</process>
+
+<success_criteria>
+- Correct signal type(s) chosen for the task
+- No `null` or `undefined` in signal generics (`T extends {}`)
+- Every `createEffect` is inside a `createScope` or another effect
+- Code follows the patterns from references/ rather than inventing new ones
+- Project's own test suite passes (if applicable)
+</success_criteria>

package/skills/cause-effect-dev/SKILL.md

@@ -7,108 +7,69 @@ description: >
 user_invocable: false
 ---
 
-# Cause & Effect — Developer Skill
+<scope>
+This skill is for development work **on the @zeix/cause-effect library itself** — use it only inside the cause-effect repository where `REQUIREMENTS.md`, `ARCHITECTURE.md`, and `src/` are present at the project root.
 
-You are an expert developer on the **@zeix/cause-effect** reactive state management primitives library (v1.0.0). Work only from authoritative sources listed below. Never guess API shapes or behaviors — read the source.
+For consumer projects that use `@zeix/cause-effect` as a dependency, use the `cause-effect` skill instead.
+</scope>
 
-## Authoritative Sources
+<essential_principles>
+**Read before writing.** Always read the relevant source file(s) before proposing or making changes.
 
-| What you need | Where to look |
+**The signal type set is complete.** Check `REQUIREMENTS.md` before proposing anything new — new signal types are explicitly out of scope.
+
+**`T extends {}`** — all signal generics exclude `null` and `undefined`. Use wrapper types or sentinel values to represent absence.
+
+**Run `bun test`** after every change.
+</essential_principles>
+
+<intake>
+What kind of task is this?
+
+1. **Implement** — add or extend functionality
+2. **Fix** — debug or fix unexpected behavior
+3. **Test** — write or update tests
+4. **Question** — understand the API, internals, or a design decision
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
 |---|---|
-| Vision, audience, constraints, non-goals | `REQUIREMENTS.md` |
-| Mental model, non-obvious behaviors, TS constraints | `CLAUDE.md` |
-| Full API reference with examples | `README.md` |
-| Mapping from React/Vue/Angular patterns; when to use each signal type | `GUIDE.md` |
-| Graph engine architecture, node shapes, propagation | `ARCHITECTURE.md` |
-| Public API surface (all exports, types) | `index.ts` |
-| Core graph engine (flags, propagation, flush, ownership) | `src/graph.ts` |
-| Error classes | `src/errors.ts` |
-| Signal base types and type guards | `src/signal.ts` |
-| Shared utilities | `src/util.ts` |
-
-## Source File Map
-
-Each signal type lives in its own file:
-
-| Signal | File | Create | Type guard |
-|---|---|---|---|
-| State | `src/nodes/state.ts` | `createState()` | `isState()` |
-| Sensor | `src/nodes/sensor.ts` | `createSensor()` | `isSensor()` |
-| Memo | `src/nodes/memo.ts` | `createMemo()` | `isMemo()` |
-| Task | `src/nodes/task.ts` | `createTask()` | `isTask()` |
-| Effect | `src/nodes/effect.ts` | `createEffect()` | — |
-| Slot | `src/nodes/slot.ts` | `createSlot()` | `isSlot()` |
-| Store | `src/nodes/store.ts` | `createStore()` | `isStore()` |
-| List | `src/nodes/list.ts` | `createList()` | `isList()` |
-| Collection | `src/nodes/collection.ts` | `createCollection()` / `deriveCollection()` | `isCollection()` |
-
-`match()` and `MatchHandlers` live in `src/nodes/effect.ts` alongside `createEffect`.
-
-## Internal Node Shapes
-
-```
-StateNode<T>  — source only
-MemoNode<T>   — source + sink (also used by Slot, Store, List, Collection internals)
-TaskNode<T>   — source + sink + AbortController
-EffectNode    — sink + owner
-Scope         — owner only
-```
-
-Two independent global pointers:
-- `activeSink` — tracked for dependency edges (nulled by `untrack()`)
-- `activeOwner` — tracked for cleanup registration (nulled by `unown()`)
-
-## Key API Facts
-
-- **`T extends {}`** — all signal generics exclude `null` and `undefined`. Use wrapper types or sentinel values to represent absence.
-- **`createScope(fn)`** — returns a single `Cleanup` function. `fn` receives no arguments and returns an optional cleanup.
-- **`createEffect(fn)`** — returns a `Cleanup`. Must be called inside an owner (effect or scope).
-- **`batch(fn)`** — defers flush until `fn` returns; multiple state writes coalesce into one propagation.
-- **`untrack(fn)`** — runs `fn` without recording dependency edges (nulls `activeSink`).
-- **`unown(fn)`** — runs `fn` without registering cleanup in the current owner (nulls `activeOwner`). Use in `connectedCallback` for DOM-owned lifecycles.
-- **`SKIP_EQUALITY`** — sentinel for `options.equals`; forces propagation on every update (use with mutable-reference sensors).
-- **Memo/Task callbacks receive `prev`** — the previous value as first argument, enabling reducer patterns without external state.
-- **`Slot` is a property descriptor** — has `get`, `set`, `configurable`, `enumerable`; can be passed directly to `Object.defineProperty()`.
-
-## Non-Obvious Behaviors
-
-**`byKey()`, `at()`, `keyAt()`, `indexOfKey()` do not create graph edges.** They are direct lookups. To react to structural changes (key added/removed), read `get()`, `keys()`, or `length`.
-
-**Conditional reads delay `watched` activation.** Read signals eagerly before conditional logic to ensure `watched` fires immediately:
-
-```typescript
-// Good — both signals tracked on every run
-createEffect(() => {
-  match([task, derived], { ok: ([r, v]) => render(v, r), nil: () => showSpinner() })
-})
-
-// Bad — derived only tracked after task resolves
-createEffect(() => {
-  match([task], { ok: ([r]) => render(derived.get(), r), nil: () => showSpinner() })
-})
-```
-
-**`equals` suppresses entire subtrees.** When a Memo recomputes to the same value, downstream nodes receive `FLAG_CHECK` and are skipped without running. A custom `equals` on an intermediate Memo can suppress whole subgraphs.
-
-**`watched` stays stable through mutations.** Structural mutations on a List/Collection source do not restart the `watched` callback; it stays active as long as any downstream effect is subscribed.
-
-## Error Classes
-
-| Class | When thrown |
+| 1, "implement", "add", "extend", "build" | workflows/implement-feature.md |
+| 2, "fix", "bug", "debug", "broken", "wrong" | workflows/fix-bug.md |
+| 3, "test", "spec", "coverage" | workflows/write-tests.md |
+| 4, "question", "explain", "how", "why", "what" | workflows/answer-question.md |
+
+**Intent-based routing** (if user provides clear context without selecting):
+- Describes a change to make → workflows/implement-feature.md
+- Describes something not working → workflows/fix-bug.md
+- Asks to write/update tests → workflows/write-tests.md
+- Asks how something works → workflows/answer-question.md
+
+**After identifying the workflow, read it and follow it exactly.**
+</routing>
+
+<reference_index>
+All in `references/`:
+
+| File | Contents |
+|---|---|
+| source-map.md | Authoritative documents + signal source file locations |
+| internal-types.md | Node shapes and global pointers |
+| api-facts.md | Key API constraints and callback patterns |
+| non-obvious-behaviors.md | Counterintuitive behaviors with examples |
+| error-classes.md | Error classes and when they are thrown |
+</reference_index>
+
+<workflows_index>
+All in `workflows/`:
+
+| Workflow | Purpose |
 |---|---|
-| `NullishSignalValueError` | Signal value is `null` or `undefined` |
-| `InvalidSignalValueError` | Value fails the `guard` check |
-| `InvalidCallbackError` | A required callback argument is not a function |
-| `DuplicateKeyError` | List/Collection key collision |
-| `UnsetSignalValueError` | Reading a Sensor/Task before it has produced a value |
-| `ReadonlySignalError` | Writing to a read-only signal |
-| `RequiredOwnerError` | `createEffect` called outside an owner |
-| `CircularDependencyError` | Cycle detected in the graph |
-
-## Workflow
-
-1. **Read before writing.** Always read the relevant source file(s) before proposing or making changes.
-2. **Check `ARCHITECTURE.md`** for graph-level questions (propagation, ownership, flag semantics).
-3. **Check `README.md`** for public API usage patterns and option signatures.
-4. **Check `REQUIREMENTS.md`** before adding anything new — the signal type set is complete and new types are explicitly out of scope.
-5. **Run `bun test`** after changes to verify correctness.
+| implement-feature.md | Add or extend library functionality |
+| fix-bug.md | Diagnose and fix unexpected behavior |
+| write-tests.md | Write or update tests for a signal type or behavior |
+| answer-question.md | Answer questions about the API, internals, or design |
+</workflows_index>