seitu 0.16.0 → 0.16.1

package/skills/{create-web-storage-value/SKILL.md → seitu/references/create-web-storage-value.md}

@@ -1,17 +1,3 @@
----
-name: create-web-storage-value
-description: >-
-  Single-key localStorage/sessionStorage with schema validation.
-type: core
-library: seitu
-library_version: "0.16.0"
-requires:
-  - seitu-overview
-sources:
-  - letstri/seitu:docs/content/docs/web/web-storage-value.mdx
-  - letstri/seitu:seitu/src/web/web-storage-value.ts
----
-
 # createWebStorageValue
 
 Single-key reactive handle for web storage. Two overloads: standalone (with schema) or derived from a WebStorage instance.
@@ -61,6 +47,7 @@ Inherits schema, default, and storage type from the parent.
 ```ts
 interface WebStorageValue<V> extends Subscribable<V>, Readable<V>, Writable<V>, Clearable {}
 ```
+
 ## Common Mistakes
 
 ### [HIGH] Accessing storage during SSR without defaults
@@ -115,4 +102,4 @@ Each instance uses a different storage subscription; use module singleton or use
 
 ## Source
 
-`src/web/web-storage-value.ts`
+`src/web/web-storage-value.ts`

package/skills/{create-web-storage/SKILL.md → seitu/references/create-web-storage.md}

@@ -1,18 +1,3 @@
----
-name: create-web-storage
-description: >-
-  Multi-key localStorage/sessionStorage with per-key schemas.
-type: core
-library: seitu
-library_version: "0.16.0"
-requires:
-  - seitu-overview
-  - create-web-storage-value
-sources:
-  - letstri/seitu:docs/content/docs/web/web-storage.mdx
-  - letstri/seitu:seitu/src/web/web-storage.ts
----
-
 # createWebStorage
 
 Multi-key reactive handle for `localStorage` or `sessionStorage`. Each key is validated by a Standard Schema.
@@ -66,6 +51,7 @@ const storage = createWebStorage({
   keyTransform: key => `myapp:${String(key)}`,
 })
 ```
+
 ## Common Mistakes
 
 ### [MEDIUM] Mixing storage types on one instance
@@ -118,8 +104,8 @@ storage event handling depends on implementation; verify subscribe fires on exte
 
 ## See also
 
-- [`create-web-storage-value`](../create-web-storage-value/SKILL.md) — Multi-key storage exposes single-key handles via createWebStorageValue.
+- [`create-web-storage-value`](create-web-storage-value.md) — Multi-key storage exposes single-key handles via createWebStorageValue.
 
 ## Source
 
-`src/web/web-storage.ts`
+`src/web/web-storage.ts`

package/skills/{use-subscription-react/SKILL.md → seitu/references/react.md}

@@ -1,22 +1,10 @@
----
-name: use-subscription-react
-description: >-
-  React hook for any Seitu primitive via useSyncExternalStore.
-type: framework
-library: seitu
-library_version: "0.16.0"
-requires:
-  - seitu-overview
-sources:
-  - letstri/seitu:docs/content/docs/react/hooks.mdx
-  - letstri/seitu:seitu/src/react/hooks.ts
----
-
-# useSubscription (React)
+# React (seitu/react)
+
+## useSubscription
 
 Core React hook from `seitu/react`. Built on `useSyncExternalStore` for concurrent-safe reads. Works with any `Subscribable<T> & Readable<T>`.
 
-## Basic usage (module-level instance)
+### Basic usage (module-level instance)
 
 ```tsx
 'use client'
@@ -31,7 +19,7 @@ function Counter() {
 }
 ```
 
-## Factory function (inline creation)
+### Factory function (inline creation)
 
 ```tsx
 'use client'
@@ -48,13 +36,13 @@ function ScrollTracker() {
 }
 ```
 
-## With selector (granular re-renders)
+### With selector (granular re-renders)
 
 ```tsx
 const count = useSubscription(storage, { selector: v => v.count })
 ```
 
-## With deps (re-create on prop change)
+### With deps (re-create on prop change)
 
 ```tsx
 function UserStorage({ userId }: { userId: string }) {
@@ -65,13 +53,38 @@ function UserStorage({ userId }: { userId: string }) {
 }
 ```
 
-## Options
+### Options
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `selector?` | `(value) => R` | Derive subset; re-render only when it changes |
 | `deps?` | `DependencyList` | Re-create factory subscription when deps change |
 | `isEqual?` | `(prev, next) => boolean` | Custom equality (default: `deepEqual`) |
+
+## Subscription (render-prop component)
+
+Declarative render-prop component from `seitu/react`. Isolates re-renders to the children function.
+
+```tsx
+import { Subscription } from 'seitu/react'
+
+<Subscription value={storage}>
+  {(value) => <div>{value.count}</div>}
+</Subscription>
+
+<Subscription value={storage} selector={v => v.count}>
+  {(count) => <div>{count}</div>}
+</Subscription>
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `Subscribable & Readable` | The reactive source |
+| `selector?` | `(value) => R` | Optional selector for granular updates |
+| `children` | `(value) => ReactNode` | Render function |
+
 ## Common Mistakes
 
 ### [CRITICAL] Missing use client directive
@@ -93,7 +106,7 @@ export default function Page() {
 }
 ```
 
-Hook uses client-only APIs; fails in RSC server components.
+Hook (and the `Subscription` component, which uses it internally) uses client-only APIs; fails in RSC server components.
 
 ### [CRITICAL] Factory without deps when props change
 
@@ -109,7 +122,7 @@ Correct:
 useSubscription(() => createWebStorageValue({ key: userId, ... }), { deps: [userId] })
 ```
 
-Factory runs once unless deps array changes.
+Factory runs once unless deps array changes. Same applies to a `Subscription` inline source — key it or pass deps.
 
 ### [HIGH] Using useEffect to subscribe manually
 
@@ -127,10 +140,26 @@ const v = useSubscription(store)
 
 useSubscription handles subscribe/unsubscribe and concurrent safety.
 
+### [LOW] Preferring component over hook without reason
+
+Wrong:
+
+```ts
+<Subscription source={s}>{v => <Child value={v} />}</Subscription>
+```
+
+Correct:
+
+```ts
+const v = useSubscription(s); return <Child value={v} />
+```
+
+useSubscription is simpler for most cases; Subscription is for render-prop composition (isolating re-renders to a subtree).
+
 ## See also
 
-- [`create-scroll-state`](../create-scroll-state/SKILL.md) — Scroll tracking requires factory + ref pattern in React.
+- [`create-scroll-state`](create-scroll-state.md) — Scroll tracking requires factory + ref pattern in React.
 
 ## Source
 
-`src/react/hooks.ts`
+`src/react/hooks.ts`, `src/react/components.tsx`

package/skills/{use-subscription-solid/SKILL.md → seitu/references/solid.md}

@@ -1,22 +1,10 @@
----
-name: use-subscription-solid
-description: >-
-  Solid primitive returning an Accessor for any Seitu primitive.
-type: framework
-library: seitu
-library_version: "0.16.0"
-requires:
-  - seitu-overview
-sources:
-  - letstri/seitu:docs/content/docs/solid/hooks.mdx
-  - letstri/seitu:seitu/src/solid/hooks.ts
----
-
-# useSubscription (Solid)
+# Solid (seitu/solid)
+
+## useSubscription
 
 Core Solid primitive from `seitu/solid`. Returns a Solid `Accessor<T>` (`() => T`) that stays in sync with the source. Works with any `Subscribable<T> & Readable<T>`. Accepts a raw instance or a reactive getter.
 
-## Basic usage (module-level instance)
+### Basic usage (module-level instance)
 
 ```tsx
 import { useSubscription } from 'seitu/solid'
@@ -30,7 +18,7 @@ function Counter() {
 }
 ```
 
-## Inline subscription (getter form)
+### Inline subscription (getter form)
 
 ```tsx
 import { useSubscription } from 'seitu/solid'
@@ -45,7 +33,7 @@ function ScrollTracker() {
 }
 ```
 
-## Reactive source (re-subscribes when a signal changes)
+### Reactive source (re-subscribes when a signal changes)
 
 ```tsx
 import { createSignal } from 'solid-js'
@@ -60,24 +48,49 @@ function UserStorage(props: { userId: string }) {
 }
 ```
 
-## With selector (granular updates)
+### With selector (granular updates)
 
 ```tsx
 const count = useSubscription(storage, { selector: v => v.count })
 // count() only changes when the selected value changes
 ```
 
-## Options
+### Options
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `selector?` | `(value) => R` | Derive subset; the accessor updates only when it changes |
 | `isEqual?` | `(prev, next) => boolean` | Custom equality (default: `deepEqual`) |
 
-## Returns
+### Returns
 
 `Accessor<R>` — a getter function. Read it with `value()` inside JSX or any tracked scope.
 
+## Subscription (render-prop component)
+
+Declarative render-prop component from `seitu/solid`. The children function runs once and
+receives a Solid `Accessor<R>` — read it with `value()` so updates stay fine-grained.
+
+```tsx
+import { Subscription } from 'seitu/solid'
+
+<Subscription value={storage}>
+  {value => <div>{value().count}</div>}
+</Subscription>
+
+<Subscription value={storage} selector={v => v.count}>
+  {count => <div>{count()}</div>}
+</Subscription>
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `Subscribable & Readable` | The reactive source |
+| `selector?` | `(value) => R` | Optional selector for granular updates |
+| `children` | `(value: Accessor<R>) => JSX.Element` | Render function receiving an accessor |
+
 ## Common Mistakes
 
 ### [CRITICAL] Reading the accessor without calling it
@@ -96,7 +109,7 @@ const value = useSubscription(store)
 return <div>{value()}</div>
 ```
 
-`useSubscription` returns a Solid `Accessor`; you must call it (`value()`) to read and track the value.
+`useSubscription` returns a Solid `Accessor`; you must call it (`value()`) to read and track the value. The same applies to the `Subscription` component's children argument — call it (`value()`) inside JSX, don't treat it as a plain value.
 
 ### [HIGH] Passing reactive props directly instead of a getter
 
@@ -132,13 +145,28 @@ Correct:
 import { useSubscription } from 'seitu/solid'
 ```
 
-Solid apps must use the `seitu/solid` primitive — the React hook relies on `useSyncExternalStore`.
+Solid apps must use the `seitu/solid` primitive/component — the React versions rely on `useSyncExternalStore` and React internals.
+
+### [LOW] Preferring the component over the primitive without reason
+
+Wrong:
+
+```tsx
+<Subscription value={s}>{v => <Child value={v()} />}</Subscription>
+```
+
+Correct:
+
+```tsx
+const v = useSubscription(s); return <Child value={v()} />
+```
+
+`useSubscription` is simpler for most cases; `Subscription` is for render-prop composition.
 
 ## See also
 
-- [`subscription-solid`](../subscription-solid/SKILL.md) — Render-prop component alternative.
-- [`create-scroll-state`](../create-scroll-state/SKILL.md) — Scroll tracking uses the getter + ref pattern in Solid.
+- [`create-scroll-state`](create-scroll-state.md) — Scroll tracking uses the getter + ref pattern in Solid.
 
 ## Source
 
-`src/solid/hooks.ts`
+`src/solid/hooks.ts`, `src/solid/components.ts`

package/skills/{use-subscription-svelte/SKILL.md → seitu/references/svelte.md}

@@ -1,25 +1,13 @@
----
-name: use-subscription-svelte
-description: >-
-  Svelte binding returning a Readable store for any Seitu primitive.
-type: framework
-library: seitu
-library_version: "0.16.0"
-requires:
-  - seitu-overview
-sources:
-  - letstri/seitu:docs/content/docs/svelte/hooks.mdx
-  - letstri/seitu:seitu/src/svelte/hooks.ts
----
-
-# useSubscription (Svelte)
+# Svelte (seitu/svelte)
+
+## useSubscription
 
 Binding from `seitu/svelte`. Returns a Svelte [`Readable`](https://svelte.dev/docs/svelte-store#readable)
 store that stays in sync with any `Subscribable<T> & Readable<T>`. Read it with the `$`
 auto-subscription (`$value`) in markup. The source subscription is created lazily on the
 first subscriber and torn down when the last one leaves (SSR-safe, auto-cleanup).
 
-## Basic usage (module-level instance)
+### Basic usage (module-level instance)
 
 ```svelte
 <script lang="ts">
@@ -33,7 +21,7 @@ first subscriber and torn down when the last one leaves (SSR-safe, auto-cleanup)
 <button onclick={() => count.set(v => v + 1)}>{$value}</button>
 ```
 
-## Inline subscription (factory form)
+### Inline subscription (factory form)
 
 ```svelte
 <script lang="ts">
@@ -52,7 +40,7 @@ first subscriber and torn down when the last one leaves (SSR-safe, auto-cleanup)
 <div>{$value}</div>
 ```
 
-## With selector (granular updates)
+### With selector (granular updates)
 
 ```svelte
 <script lang="ts">
@@ -62,14 +50,14 @@ first subscriber and torn down when the last one leaves (SSR-safe, auto-cleanup)
 <div>{$count}</div>
 ```
 
-## Options
+### Options
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `selector?` | `(value) => R` | Derive a subset; the store updates only when it changes |
 | `isEqual?` | `(prev, next) => boolean` | Custom equality (default: `deepEqual`) |
 
-## Returns
+### Returns
 
 `Readable<R>` (from `svelte/store`) — read it as `$value` in markup, or with `get(value)` in scripts.
 

package/skills/{use-subscription-vue/SKILL.md → seitu/references/vue.md}

@@ -1,22 +1,10 @@
----
-name: use-subscription-vue
-description: >-
-  Vue composable returning readonly ShallowRef.
-type: framework
-library: seitu
-library_version: "0.16.0"
-requires:
-  - seitu-overview
-sources:
-  - letstri/seitu:docs/content/docs/vue/composables.mdx
-  - letstri/seitu:seitu/src/vue/composables.ts
----
-
-# useSubscription (Vue)
+# Vue (seitu/vue)
+
+## useSubscription
 
 Vue 3 composable from `seitu/vue`. Returns a readonly `ShallowRef<T>` that stays in sync with the source. Accepts a raw instance, a `ref`, or a getter.
 
-## Basic usage
+### Basic usage
 
 ```vue
 <script setup lang="ts">
@@ -39,7 +27,7 @@ const value = useSubscription(count)
 </template>
 ```
 
-## With reactive source (auto re-subscribes)
+### With reactive source (auto re-subscribes)
 
 ```vue
 <script setup lang="ts">
@@ -62,7 +50,7 @@ const data = useSubscription(storage)
 </script>
 ```
 
-## With selector
+### With selector
 
 ```vue
 <script setup lang="ts">
@@ -70,12 +58,13 @@ const count = useSubscription(storage, { selector: v => v.count })
 </script>
 ```
 
-## Options
+### Options
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `selector?` | `(value) => R` | Derive subset; update ref only when it changes |
 | `isEqual?` | `(prev, next) => boolean` | Custom equality (default: `deepEqual`) |
+
 ## Common Mistakes
 
 ### [HIGH] Destructuring the returned ref
@@ -129,4 +118,4 @@ Vue apps must use seitu/vue composable.
 
 ## Source
 
-`src/vue/composables.ts`
+`src/vue/composables.ts`

package/skills/seitu-overview/SKILL.md

@@ -2,9 +2,10 @@
 name: seitu-overview
 description: >-
   Module map, mental model, decision tree, SSR — read before other Seitu skills.
-type: lifecycle
-library: seitu
-library_version: "0.16.0"
+metadata:
+  type: lifecycle
+  library: seitu
+  library_version: "0.16.1"
 sources:
   - letstri/seitu:docs/content/docs/index.mdx
   - letstri/seitu:seitu/src/core/index.ts
@@ -165,10 +166,11 @@ const settings = createWebStorageValue({
 })
 ```
 
-## Per-function skills
+## Per-function reference
 
-Each exported function has a dedicated skill in `skills/<slug>/SKILL.md` (lowercase-hyphen slug, e.g. `create-store`).
-Read the overview first, then the specific skill for the function you need.
+The **seitu** skill has a reference file per primitive and framework binding
+in `skills/seitu/references/<slug>.md` (e.g. `create-store.md`). Read this
+overview first, then the specific reference for the function you need.
 ## Common Mistakes
 
 ### [HIGH] Using useState for shared module-level state
@@ -229,7 +231,7 @@ Seitu has no dispatch layer — mutate with .set() directly.
 
 ## See also
 
-- [`create-web-storage-value`](../create-web-storage-value/SKILL.md) — Decision tree routes persistence tasks to web storage skills.
+- [`create-web-storage-value`](../seitu/references/create-web-storage-value.md) — Decision tree routes persistence tasks to web storage skills.
 
 ## Source
 

package/skills/subscription-react/SKILL.md

@@ -1,96 +0,0 @@
----
-name: subscription-react
-description: >-
-  Render-prop Subscription component for React.
-type: framework
-library: seitu
-library_version: "0.16.0"
-requires:
-  - seitu-overview
-  - use-subscription-react
-sources:
-  - letstri/seitu:docs/content/docs/react/components.mdx
-  - letstri/seitu:seitu/src/react/components.tsx
----
-
-# Subscription (React component)
-
-Declarative render-prop component from `seitu/react`. Isolates re-renders to the children function.
-
-```tsx
-import { Subscription } from 'seitu/react'
-
-<Subscription value={storage}>
-  {(value) => <div>{value.count}</div>}
-</Subscription>
-
-<Subscription value={storage} selector={v => v.count}>
-  {(count) => <div>{count}</div>}
-</Subscription>
-```
-
-## Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `value` | `Subscribable & Readable` | The reactive source |
-| `selector?` | `(value) => R` | Optional selector for granular updates |
-| `children` | `(value) => ReactNode` | Render function |
-## Common Mistakes
-
-### [CRITICAL] Using without use client
-
-Wrong:
-
-```ts
-export function Page() {
-  return <Subscription source={store}>{v => v}</Subscription>
-}
-```
-
-Correct:
-
-```ts
-'use client'
-export function Page() {
-  return <Subscription source={store}>{v => v}</Subscription>
-}
-```
-
-Component uses hooks internally.
-
-### [HIGH] Inline source factory without key/deps
-
-Wrong:
-
-```ts
-<Subscription source={() => createStore(prop)}>{...}</Subscription>
-```
-
-Correct:
-
-```ts
-<Subscription key={prop} source={() => createStore(prop)}>{...}</Subscription>
-```
-
-Same as hook — factory recreates only when React remounts.
-
-### [LOW] Preferring component over hook without reason
-
-Wrong:
-
-```ts
-<Subscription source={s}>{v => <Child value={v} />}</Subscription>
-```
-
-Correct:
-
-```ts
-const v = useSubscription(s); return <Child value={v} />
-```
-
-useSubscription is simpler for most cases; Subscription for render-prop composition.
-
-## Source
-
-`src/react/components.tsx`