fetchium 0.1.0 → 0.2.0

package/plugin/docs/setup/project-setup.md

@@ -0,0 +1,319 @@
+---
+title: Project Setup
+---
+
+The [Quick Start](/quickstart) gets you from zero to a running query in five steps. This page goes deeper --- it explains _what_ each piece of the setup does, _why_ it exists, and how to configure it for a real production application.
+
+If you are coming from libraries like TanStack Query or SWR, you may be used to creating a client object and passing it through React context. Fetchium follows a similar pattern, but with a few key differences: the `QueryClient` is _not_ a React-specific concept (it works in any JavaScript environment), it delegates persistence to a _pluggable store_, and it uses Signalium's context system rather than React's built-in `createContext`.
+
+---
+
+## The QueryClient
+
+The `QueryClient` is the central coordinator of a Fetchium application. It manages:
+
+- **Query instances** --- deduplicating in-flight requests, caching results, scheduling refetches
+- **The entity store** --- normalizing, deduplicating, and storing entities by typename + id
+- **Garbage collection** --- evicting unused queries and entities from memory
+- **Network awareness** --- pausing and resuming queries based on connectivity
+
+Every Fetchium operation --- `fetchQuery`, `useQuery`, `getMutation` --- looks up the `QueryClient` from a Signalium context. If no client is found, these calls will throw.
+
+### Creating a QueryClient
+
+The `QueryClient` constructor takes a single config object. The only required field is `store`:
+
+```tsx
+import { QueryClient } from 'fetchium';
+import { SyncQueryStore, MemoryPersistentStore } from 'fetchium/stores/sync';
+import { RESTQueryAdapter } from 'fetchium/rest';
+
+const client = new QueryClient({
+  store: new SyncQueryStore(new MemoryPersistentStore()),
+  adapters: [
+    new RESTQueryAdapter({
+      fetch: globalThis.fetch,
+      baseUrl: 'https://api.example.com',
+    }),
+  ],
+});
+```
+
+The store is responsible for _persistent_ caching --- saving query results and entity data so they survive page refreshes, app restarts, or being evicted from the in-memory cache. `MemoryPersistentStore` keeps everything in memory (data is lost on refresh), which is perfect for development and tests. For production persistence, implement the `SyncPersistentStore` interface with a durable backend like `localStorage`, or use the `AsyncQueryStore` with IndexedDB. See the [Offline & Persistence](/guides/offline) guide for details.
+
+### QueryClientConfig options
+
+| Option     | Type             | Default                      | Description                                                                                                                  |
+| ---------- | ---------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `store`    | `QueryStore`     | `SyncQueryStore` (in-memory) | Persistent storage backend for query results and entity data. Defaults to an in-memory store — data is lost on page refresh. |
+| `adapters` | `QueryAdapter[]` | `[]`                         | Transport adapters. Register a `RESTQueryAdapter` to configure `fetch`, `baseUrl`, and headers for REST queries.             |
+| `log`      | `object`         | `console`                    | A logger with `warn` and `error` methods. Fetchium uses `log.warn` for non-fatal parse failures.                             |
+
+### Auto-instantiation
+
+Both the store and adapters have sensible defaults, so the minimal `QueryClient` requires no configuration at all:
+
+```tsx
+// Fully minimal — in-memory store, RESTQueryAdapter auto-instantiated on first use
+const client = new QueryClient();
+```
+
+- `store` defaults to `SyncQueryStore(MemoryPersistentStore)` — data lives in memory and is lost on page refresh
+- Adapters are auto-instantiated from their base class the first time a query of that type runs. `RESTQueryAdapter` has a no-arg constructor that defaults to `globalThis.fetch`
+
+Once you need a `baseUrl`, auth headers, persistent storage, or a custom fetch wrapper, pass explicit options.
+
+### The RESTQueryAdapter
+
+`RESTQueryAdapter` is the transport layer for all REST queries and mutations. It accepts:
+
+| Option    | Type       | Default            | Description                                                                                                                                                     |
+| --------- | ---------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fetch`   | `Function` | `globalThis.fetch` | The fetch function used for all network requests. Pass a custom wrapper for auth headers, logging, or testing.                                                  |
+| `baseUrl` | `string`   | `''`               | Prepended to every query path. Set this to your API root (`https://api.example.com`) so your query paths can be relative (`/users/42` instead of the full URL). |
+
+`fetch` is the _single point of control_ for how Fetchium makes network requests. Every REST query and mutation flows through this function, which means you can add authentication, logging, retry logic, or any other cross-cutting concern in one place. We cover this in depth in the [Auth & Headers](/guides/auth) guide.
+
+{% callout title="Why pass fetch explicitly?" type="note" %}
+You might wonder why Fetchium asks you to pass `fetch` instead of just using the global. The reason is _testability_ and _universality_. By accepting `fetch` as a parameter, Fetchium works identically in browsers, Node.js, Deno, and test environments. In tests, you pass a mock fetch. On the server, you pass Node's fetch. In the browser, you pass a wrapper that adds auth headers. The interface is always the same.
+{% /callout %}
+
+### Providing the client to your app
+
+The `QueryClient` is made available to your component tree through Signalium's `ContextProvider`. This is analogous to React's `Context.Provider`, but works with Signalium's reactive context system:
+
+```tsx
+import { QueryClient, QueryClientContext } from 'fetchium';
+import { SyncQueryStore, MemoryPersistentStore } from 'fetchium/stores/sync';
+import { RESTQueryAdapter } from 'fetchium/rest';
+import { ContextProvider } from 'signalium/react';
+
+const client = new QueryClient({
+  store: new SyncQueryStore(new MemoryPersistentStore()),
+  adapters: [
+    new RESTQueryAdapter({
+      fetch: globalThis.fetch,
+      baseUrl: 'https://api.example.com',
+    }),
+  ],
+});
+
+function App() {
+  return (
+    <ContextProvider value={client} context={QueryClientContext}>
+      <YourApp />
+    </ContextProvider>
+  );
+}
+```
+
+Any component or reactive function inside this provider can now call `useQuery`, `fetchQuery`, or `getMutation`, and they will automatically find the client.
+
+{% callout title="If you are using Signalium mode" type="note" %}
+When using `component()` from `signalium/react`, the `ContextProvider` is the standard way to provide contexts. If you are using `useQuery` with plain React hooks, you still need the `ContextProvider` --- the hook reads from the Signalium context internally.
+{% /callout %}
+
+---
+
+## The Babel Transform
+
+Signalium includes a Babel transform that enables two features:
+
+1. **Async reactivity** --- rewriting `async` functions used with `reactive()` into generator-based coroutines, so Signalium can track dependencies across `await` boundaries
+2. **Callback tracking** --- wrapping callback arguments for reactive tracking inside event handlers
+
+The transform is _optional_ if you only use `useQuery` with plain React hooks. It becomes _necessary_ when you use Signalium's `reactive()` with `async` functions, which is one of the most powerful patterns for composing queries.
+
+### Vite + React
+
+```js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { signaliumPreset } from 'signalium/transform';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        presets: [signaliumPreset()],
+      },
+    }),
+  ],
+});
+```
+
+### Next.js
+
+```js
+// next.config.js
+const withSignalium = require('signalium/transform/next');
+
+module.exports = withSignalium({
+  // your Next.js config
+});
+```
+
+### Generic Babel config
+
+```js
+// babel.config.js
+import { signaliumPreset } from 'signalium/transform';
+
+module.exports = {
+  presets: [
+    '@babel/preset-env',
+    '@babel/preset-react',
+    '@babel/preset-typescript',
+    signaliumPreset(),
+  ],
+};
+```
+
+The transform only affects code that uses Signalium APIs (`reactive`, `relay`, `task`). Standard async/await outside of reactive contexts is untouched. For a deeper look at what the transform does and when you need it, see [Why Signalium?](/reference/why-signalium).
+
+---
+
+## Project Structure
+
+Fetchium does not enforce a particular file layout, but after working with it across projects, a pattern has emerged that works well.
+
+### Recommended layout
+
+```
+src/
+  api/
+    client.ts          # QueryClient creation and configuration
+    entities/           # Entity class definitions
+      User.ts
+      Post.ts
+      Comment.ts
+    queries/            # Query class definitions
+      GetUser.ts
+      GetPosts.ts
+      GetFeed.ts
+    mutations/          # Mutation class definitions
+      CreatePost.ts
+      UpdateUser.ts
+    reactive/           # Shared reactive functions (Signalium mode)
+      useUserProfile.ts
+      useFeed.ts
+  components/
+    ...
+```
+
+The key principle is _separation of data definitions from UI_. Your entity and query classes are plain TypeScript --- they have no dependency on React, no JSX, no component logic. This makes them testable, reusable across frameworks, and easy to reason about independently.
+
+### Entity files
+
+Each entity gets its own file. Entities tend to be referenced across many queries and mutations, so isolating them prevents circular imports:
+
+```ts
+// src/api/entities/User.ts
+import { Entity, t } from 'fetchium';
+
+export class User extends Entity {
+  __typename = t.typename('User');
+  id = t.id;
+
+  name = t.string;
+  email = t.string;
+  avatar = t.optional(t.string);
+}
+```
+
+### Query files
+
+Queries import from entities and define the API surface:
+
+```ts
+// src/api/queries/GetUser.ts
+import { t } from 'fetchium';
+import { RESTQuery } from 'fetchium/rest';
+import { User } from '../entities/User';
+
+export class GetUser extends RESTQuery {
+  params = { id: t.number };
+
+  path = `/users/${this.params.id}`;
+
+  result = { user: t.entity(User) };
+}
+```
+
+### The client file
+
+A single file creates and exports the `QueryClient`. This is the place to configure `baseUrl`, auth wrappers, and logging:
+
+```ts
+// src/api/client.ts
+import { QueryClient } from 'fetchium';
+import { SyncQueryStore, MemoryPersistentStore } from 'fetchium/stores/sync';
+import { RESTQueryAdapter } from 'fetchium/rest';
+
+export const queryClient = new QueryClient({
+  store: new SyncQueryStore(new MemoryPersistentStore()),
+  adapters: [
+    new RESTQueryAdapter({
+      fetch: globalThis.fetch,
+      baseUrl: import.meta.env.VITE_API_URL ?? 'https://api.example.com',
+    }),
+  ],
+});
+```
+
+### Shared reactive functions (Signalium mode)
+
+If you are using Signalium, shared `reactive()` functions that compose multiple queries live in their own directory. These form a _reactive data layer_ between your raw API queries and your components:
+
+```ts
+// src/api/reactive/useUserProfile.ts
+import { reactive } from 'signalium';
+import { fetchQuery } from 'fetchium';
+import { GetUser } from '../queries/GetUser';
+import { GetUserPosts } from '../queries/GetUserPosts';
+
+export const getUserProfile = reactive((userId: number) => {
+  const user = fetchQuery(GetUser, { id: userId });
+  const posts = fetchQuery(GetUserPosts, { userId });
+  return { user, posts };
+});
+```
+
+This is not required --- you can call `fetchQuery` directly in components --- but extracting these functions keeps your components focused on rendering, and the reactive functions are automatically memoized and shared across consumers.
+
+---
+
+## Development vs Production
+
+Fetchium uses a compile-time constant `IS_DEV` to enable additional runtime checks in development:
+
+- **Parse validation warnings** --- detailed logs when response data doesn't match your type definitions
+- **Entity write protection** --- throws when you accidentally try to mutate an entity property directly (entities are read-only)
+- **Reference validation** --- catches common mistakes like using conditional logic in class field definitions
+
+In production builds, all `IS_DEV` code paths are tree-shaken, so there is zero runtime cost.
+
+Fetchium's `package.json` uses [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to serve different bundles:
+
+- The `development` condition serves the development build (with `IS_DEV = true`)
+- The `production` condition (and the default) serves the production build (with `IS_DEV = false`)
+
+Most bundlers (Vite, webpack, esbuild) resolve the `development` condition automatically when running in development mode. If your dev server is not picking up development warnings, check that your bundler's resolve conditions include `'development'`.
+
+---
+
+## Next Steps
+
+With your project set up, you are ready to start defining your API surface:
+
+{% quick-links %}
+
+{% quick-link title="Queries" icon="presets" href="/core/queries" description="Learn how to define queries, use them in components, and understand the template system" /%}
+
+{% quick-link title="Auth & Headers" icon="installation" href="/guides/auth" description="Add authentication tokens and custom headers to your requests" /%}
+
+{% quick-link title="Error Handling" icon="theming" href="/guides/error-handling" description="Handle failures gracefully with retries, error states, and global interceptors" /%}
+
+{% quick-link title="Testing" icon="plugins" href="/guides/testing" description="Set up a test QueryClient and mock your API layer" /%}
+
+{% /quick-links %}

package/plugin/install.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * Sets up Fetchium agent files for Claude Code and/or Cursor by creating
+ * symlinks into node_modules/fetchium/plugin/. Files stay in sync
+ * automatically when the package is updated.
+ *
+ * Usage:
+ *   npx fetchium-agents           # set up both .claude/ and .cursor/
+ *   npx fetchium-agents --cursor  # Cursor only
+ *   npx fetchium-agents --claude  # Claude Code only
+ */
+
+import { existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, rmSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = __dirname;
+const projectRoot = resolve(pluginRoot, '../../..');
+
+const args = process.argv.slice(2);
+const forceCursor = args.includes('--cursor');
+const forceClaude = args.includes('--claude');
+const installBoth = !forceCursor && !forceClaude;
+
+function symlink(target, linkPath) {
+  const linkDir = dirname(linkPath);
+  mkdirSync(linkDir, { recursive: true });
+
+  try {
+    const stat = lstatSync(linkPath);
+    if (stat.isSymbolicLink() || stat.isFile()) {
+      unlinkSync(linkPath);
+    } else if (stat.isDirectory()) {
+      rmSync(linkPath, { recursive: true });
+    }
+  } catch {
+    // doesn't exist, fine
+  }
+
+  const relTarget = relative(linkDir, target);
+  symlinkSync(relTarget, linkPath);
+}
+
+const installed = [];
+
+// --- Claude Code ---
+if (forceClaude || installBoth) {
+  symlink(join(pluginRoot, 'agents/fetchium.md'), join(projectRoot, '.claude/agents/fetchium.md'));
+  installed.push('  .claude/agents/fetchium.md');
+
+  symlink(join(pluginRoot, 'skills/design'), join(projectRoot, '.claude/skills/fetchium-design'));
+  installed.push('  .claude/skills/fetchium-design/');
+
+  symlink(join(pluginRoot, 'skills/teach'), join(projectRoot, '.claude/skills/fetchium-teach'));
+  installed.push('  .claude/skills/fetchium-teach/');
+}
+
+// --- Cursor ---
+if (forceCursor || installBoth) {
+  const cursorSkillsIsSymlink =
+    existsSync(join(projectRoot, '.cursor/skills')) && lstatSync(join(projectRoot, '.cursor/skills')).isSymbolicLink();
+
+  symlink(join(pluginRoot, 'agents/fetchium.md'), join(projectRoot, '.cursor/rules/fetchium.md'));
+  installed.push('  .cursor/rules/fetchium.md');
+
+  if (cursorSkillsIsSymlink) {
+    installed.push('  .cursor/skills/ is already symlinked — Claude Code skills are shared');
+  } else {
+    symlink(join(pluginRoot, 'skills/design'), join(projectRoot, '.cursor/skills/fetchium-design'));
+    installed.push('  .cursor/skills/fetchium-design/');
+
+    symlink(join(pluginRoot, 'skills/teach'), join(projectRoot, '.cursor/skills/fetchium-teach'));
+    installed.push('  .cursor/skills/fetchium-teach/');
+  }
+}
+
+if (installed.length > 0) {
+  console.log('\nFetchium agent files symlinked (all point to node_modules/fetchium/plugin/):\n');
+  for (const line of installed) {
+    console.log(line);
+  }
+  console.log('\nFiles stay in sync automatically when you update the fetchium package.');
+  console.log('The plugin is also available for direct use: claude --plugin-dir node_modules/fetchium/plugin\n');
+} else {
+  console.log('Nothing to do. Run with --cursor or --claude to target a specific tool.\n');
+}

package/plugin/skills/design/SKILL.md

@@ -0,0 +1,140 @@
+---
+description: Analyze an existing data model and design Fetchium entities, queries, and mutations. Use when the user wants to map an API, schema, or data model onto Fetchium primitives, plan a migration, or design a new data layer.
+---
+
+# Fetchium Design
+
+Help the user analyze an existing data model and map it onto Fetchium's primitives: Entities, Queries, and Mutations. Produce a structured design plan.
+
+## Mode
+
+If `$ARGUMENTS` contains "hooks" or "signalium", use that mode for component examples in the design plan. Otherwise, auto-detect by checking the codebase for `signalium` or `signalium/react` imports. Default to React + Hooks if neither is specified nor detected.
+
+## Process
+
+### 1. Gather the existing data model
+
+Ask the user to provide one or more of:
+
+- REST API endpoints (OpenAPI spec, route definitions, or example curl commands)
+- GraphQL schema or queries
+- TypeScript interfaces or types for API responses
+- Database schema (SQL DDL or ORM models)
+- Example JSON payloads from their API
+
+If the user hasn't provided anything yet, ask them to share their data model before proceeding.
+
+### 2. Identify Entities
+
+Entities are objects with **identity** — they have a unique typename and ID, and the same object may appear across multiple queries.
+
+Look for:
+
+- Objects with an `id` field (or similar: `_id`, `uuid`, `pk`)
+- Objects referenced by multiple endpoints or nested in other objects
+- Objects that can be created, updated, or deleted independently
+
+For each entity, note:
+
+- The typename (use the domain name: `User`, `Post`, `Comment`, etc.)
+- The ID field and type (`string` or `number`)
+- All scalar fields and their types
+- Relationships to other entities (these become `t.entity(OtherEntity)` references)
+- Any union/polymorphic types (need `t.typename(...)` discriminator)
+
+**Not everything is an entity.** Plain response wrappers, pagination metadata, and one-off objects without identity should be `t.object({ ... })`, not Entity classes.
+
+### 3. Identify Queries
+
+Map read operations to Query classes:
+
+- Each GET endpoint or GraphQL query becomes a `RESTQuery` (or custom `Query`) class
+- Identify params: path parameters, query string parameters, headers
+- Identify the result shape: which fields come back, which are entities vs plain objects
+- Note pagination patterns (offset/cursor) — these may need `sendNext()`/`hasNext()`
+- Note polling/subscription needs — these use `config.subscribe`
+
+### 4. Identify Mutations
+
+Map write operations to Mutation classes:
+
+- Each POST/PUT/PATCH/DELETE endpoint becomes a `RESTMutation` (or custom `Mutation`)
+- Identify params and body shape
+- **Critically:** identify the side effects:
+  - **Creates**: which entity type is created? Does the server return the new entity?
+  - **Updates**: which entity fields change? Can effects be declared statically from params, or do they need `getEffects()` (server response dependent)?
+  - **Deletes**: which entity is removed?
+- Note if optimistic updates are appropriate (simple, predictable changes)
+- Note if `invalidates` is needed (complex server-side logic, bulk operations)
+
+### 5. Flag issues
+
+Watch for these common problems:
+
+- **Missing IDs**: Objects that should be entities but lack an `id` field
+- **Undiscriminated unions**: Polymorphic arrays/objects without a `type`/`__typename` discriminator field
+- **Circular references**: Entity A references Entity B which references Entity A — Fetchium handles this, but note it
+- **Denormalized data**: The same entity returned with different field subsets across endpoints — design entities with `t.optional()` for fields not always present
+- **Missing typename in API**: The API may not return a `type` field — note where the client needs to inject one
+
+### 6. Produce the design plan
+
+Output a structured plan with these sections:
+
+**Entities** — list each Entity class with its fields in `t.*` DSL format:
+
+```ts
+class User extends Entity {
+  __typename = t.typename('User');
+  id = t.id;
+  name = t.string;
+  email = t.string;
+  posts = t.array(t.entity(Post));
+}
+```
+
+**Queries** — list each Query class with params, path, and result:
+
+```ts
+class GetUser extends RESTQuery {
+  params = { id: t.id };
+  path = `/users/${this.params.id}`;
+  result = { user: t.entity(User) };
+}
+```
+
+**Mutations** — list each Mutation class with params, method, body, and effects:
+
+```ts
+class UpdateUser extends RESTMutation {
+  params = { id: t.id, name: t.string };
+  path = `/users/${this.params.id}`;
+  method = 'PUT';
+  body = { name: this.params.name };
+  result = User;
+  effects = {
+    updates: [[User, { id: this.params.id, name: this.params.name }]],
+  };
+}
+```
+
+**Gaps and decisions** — list anything that needs user input:
+
+- Ambiguous entity boundaries
+- Missing discriminators that need to be added
+- Fields that might need `t.optional()` vs required
+- Polling/subscription decisions
+- Live array constraints for collections
+
+## Reference
+
+For detailed guidance on any topic, read the relevant files from `node_modules/fetchium/plugin/docs/`:
+
+- Entity definitions and proxy behavior: `node_modules/fetchium/plugin/docs/core/entities.md`
+- Query definitions and class rules: `node_modules/fetchium/plugin/docs/core/queries.md`
+- Type DSL reference: `node_modules/fetchium/plugin/docs/core/types.md`
+- Mutation effects and optimistic updates: `node_modules/fetchium/plugin/docs/data/mutations.md`
+- Live arrays and live values: `node_modules/fetchium/plugin/docs/data/live-data.md`
+- REST query configuration: `node_modules/fetchium/plugin/docs/reference/rest-queries.md`
+- Pagination patterns: `node_modules/fetchium/plugin/docs/reference/pagination.md`
+- Streaming and subscriptions: `node_modules/fetchium/plugin/docs/reference/streaming.md`

package/plugin/skills/teach/SKILL.md

@@ -0,0 +1,105 @@
+---
+description: Teach Fetchium concepts with thorough explanations, canonical examples, and documentation links. Use when the user wants to learn about Fetchium, understand how something works, or get a conceptual explanation.
+---
+
+# Fetchium Teach
+
+Enter teaching mode. Provide thorough, accurate explanations of Fetchium concepts using the full documentation. Prioritize depth and clarity over brevity.
+
+## Mode
+
+If `$ARGUMENTS` contains "hooks" or "signalium", use that mode for all examples. Otherwise, auto-detect by checking the codebase for `signalium` or `signalium/react` imports. If Signalium is detected, show Signalium-style examples; otherwise default to React + Hooks examples.
+
+## Instructions
+
+1. **Read the docs first.** Before answering any question, read the relevant documentation files from `node_modules/fetchium/plugin/docs/`. The full documentation is available there as markdown files. Always ground your answers in the actual docs.
+
+2. **Use canonical examples.** Use the examples from the documentation, not invented ones. The docs contain carefully crafted examples that demonstrate correct patterns and avoid common pitfalls.
+
+3. **Link to the docs site.** For every concept you explain, include a link to the relevant page on the Fetchium docs site. Use these base URLs:
+
+   | Topic                 | URL                                          |
+   | --------------------- | -------------------------------------------- |
+   | Quick start           | https://fetchium.dev/quickstart              |
+   | Project setup         | https://fetchium.dev/setup/project-setup     |
+   | Queries               | https://fetchium.dev/core/queries            |
+   | Types                 | https://fetchium.dev/core/types              |
+   | Entities              | https://fetchium.dev/core/entities           |
+   | Mutations             | https://fetchium.dev/data/mutations          |
+   | Live Data             | https://fetchium.dev/data/live-data          |
+   | Caching & Refetching  | https://fetchium.dev/data/caching            |
+   | Auth & Headers        | https://fetchium.dev/guides/auth             |
+   | Error Handling        | https://fetchium.dev/guides/error-handling   |
+   | Offline & Persistence | https://fetchium.dev/guides/offline          |
+   | Testing               | https://fetchium.dev/guides/testing          |
+   | REST Queries          | https://fetchium.dev/reference/rest-queries  |
+   | Pagination            | https://fetchium.dev/reference/pagination    |
+   | Streaming             | https://fetchium.dev/reference/streaming     |
+   | Why Signalium?        | https://fetchium.dev/reference/why-signalium |
+   | API: fetchium         | https://fetchium.dev/api/fetchium            |
+   | API: fetchium/react   | https://fetchium.dev/api/fetchium-react      |
+   | API: stores/sync      | https://fetchium.dev/api/stores-sync         |
+   | API: stores/async     | https://fetchium.dev/api/stores-async        |
+
+4. **Explain the mental model.** When appropriate, connect specific features to the broader Fetchium philosophy:
+   - **Query-Mutation split**: queries read (reactive, automatic), mutations write (imperative, explicit)
+   - **Entity normalization**: each `(typename, id)` maps to one proxy; updates propagate everywhere automatically
+   - **Identity-stable proxies**: same entity always returns the same object reference across all queries
+   - **Declarative effects**: mutations declare what changed (creates/updates/deletes), Fetchium handles propagation
+   - **Resilience to API evolution**: optional fields fall back gracefully, arrays filter unparseable items, discriminated unions enable safe polymorphism
+   - **Protocol agnosticism**: `RESTQuery`/`RESTMutation` are adapters; the core `Query`/`Mutation` classes work with any transport
+
+5. **Compare to other libraries when asked.** When users ask how Fetchium compares to TanStack Query, Apollo, SWR, or similar libraries, highlight:
+   - **vs TanStack Query**: Fetchium uses declarative mutation effects instead of imperative `onSuccess` callbacks. Entity normalization means updates propagate automatically without manual cache management. Queries are class-based definitions (protocol-agnostic) rather than inline hook calls.
+   - **vs Apollo Client**: Similar entity normalization goals, but Fetchium is not tied to GraphQL. Fetchium's type DSL replaces GraphQL's type system for REST APIs. No code generation step needed.
+   - **vs SWR**: SWR is focused on simple key-based caching. Fetchium adds entity normalization, typed query definitions, mutation effects, live data, and protocol adapters.
+
+6. **Teach Signalium when relevant.** Only cover Signalium concepts if the user is using Signalium (detected via imports) or explicitly asks about it. When teaching Signalium in the context of Fetchium:
+   - **Why Signalium over Hooks**: Signals eliminate the combinatorial complexity of composing multiple async operations. With Hooks, chaining two queries requires managing `isReady`/`isRejected` for both and combining their states. With Signalium's `reactive(async () => {...})`, you write sequential `await` calls and get a single `ReactivePromise` back.
+   - **Key Signalium primitives**:
+     - `signal(value)` — a reactive value. Reading it inside a reactive context creates a dependency.
+     - `reactive(() => {...})` — a derived computation that re-runs when its dependencies change. The synchronous version returns the computed value; the async version returns a `ReactivePromise`.
+     - `component(() => {...})` — wraps a React component in a reactive context. The component re-renders only when the signals it reads change, not on every parent render.
+     - `watcher(() => {...})` — runs a side effect when dependencies change (similar to `useEffect` but dependency-tracked automatically).
+   - **Fetchium + Signalium integration**: `fetchQuery()` returns a `ReactivePromise` that can be awaited inside `reactive(async () => {...})`. Multiple sequential queries compose naturally. `component()` replaces the need for `useQuery` — just call `fetchQuery()` directly inside the component body.
+   - **Reference**: Point users to `node_modules/fetchium/plugin/docs/reference/why-signalium.md` for the full explanation and to the Signalium docs at https://signalium.dev for the framework itself.
+
+7. **Provide glossary on request.** Key Fetchium terms:
+   - **Entity**: A normalized data object with identity (`typename` + `id`), stored as a proxy in the entity store
+   - **Query**: A parameterized read request. Class-based definition with `params` and `result`
+   - **Mutation**: A parameterized write request with declared side effects (`creates`/`updates`/`deletes`)
+   - **Type DSL (`t`)**: Fetchium's schema language for describing JSON shapes, used for params, results, and entity fields
+   - **ReactivePromise**: The return type of queries — wraps an async value with `isReady`, `isPending`, `isResolved`, `isRejected`, `value`, `error`
+   - **ReactiveTask**: The return type of `getMutation()` — wraps an imperative action with `.run()` and status properties
+   - **LiveArray**: A reactive array of entities that auto-updates from entity events (creates/deletes)
+   - **LiveValue**: A reactive derived value that auto-updates from entity events via reducers
+   - **Identity-stable proxy**: The Proxy object returned for each entity — same `(typename, id)` always returns the same object
+   - **Entity effects**: The `creates`/`updates`/`deletes` declarations on mutations that drive automatic cache updates
+   - **QueryClient**: The central coordinator managing query instances, entity store, cache, and context
+
+## Documentation Files
+
+All documentation files are at `node_modules/fetchium/plugin/docs/`:
+
+| File                         | Content                                                             |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `quickstart.md`              | Getting started guide                                               |
+| `setup/project-setup.md`     | Project configuration                                               |
+| `core/queries.md`            | Query definitions, class rules, usage with Hooks and Signalium      |
+| `core/types.md`              | Full type DSL reference, union rules, format system                 |
+| `core/entities.md`           | Entity definitions, proxies, methods, subscriptions, deduplication  |
+| `data/mutations.md`          | Mutation definitions, effects, optimistic updates, custom mutations |
+| `data/live-data.md`          | LiveArray, LiveValue, constraints, reducers                         |
+| `data/caching.md`            | Cache configuration, stale time, refetching                         |
+| `guides/auth.md`             | Authentication patterns, headers, context                           |
+| `guides/error-handling.md`   | Error handling, retry configuration                                 |
+| `guides/offline.md`          | Offline support, persistent stores                                  |
+| `guides/testing.md`          | Testing patterns, mock fetch, store setup                           |
+| `reference/rest-queries.md`  | RESTQuery field reference, dynamic overrides                        |
+| `reference/pagination.md`    | Pagination and infinite query patterns                              |
+| `reference/streaming.md`     | Streaming, subscriptions, real-time updates                         |
+| `reference/why-signalium.md` | Why Signalium, benefits over hooks                                  |
+| `api/fetchium.md`            | API reference for the main package                                  |
+| `api/fetchium-react.md`      | API reference for fetchium/react                                    |
+| `api/stores-sync.md`         | API reference for fetchium/stores/sync                              |
+| `api/stores-async.md`        | API reference for fetchium/stores/async                             |