@askrjs/cli 0.0.2

package/skills/askr-file-upload-artifacts/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: askr-file-upload-artifacts
+description: Use when building Askr file uploads, generated artifacts, progress, previews, validation, storage adapters, downloads, open flows, virus-scan or processing states, and event-sourced artifact readiness.
+---
+
+# Askr File Upload Artifacts
+
+Use this for uploads, downloads, previews, and generated files. The goal is one clear upload workflow, explicit processing truth, and no loss of progress or readiness state.
+
+## Use This When
+
+- You need file selection, upload, processing, preview, or download flows.
+- Artifacts may be generated asynchronously after upload.
+- You need progress, retry, cancellation, or readiness reconciliation.
+- Validation rules include type, size, count, privacy, or retention.
+
+## Inspect First
+
+- Adapter support for upload URLs, multipart uploads, or artifact APIs
+- Feature workflow for create, upload, process, and download
+- File validation rules: type, size, count, privacy, retention
+- Artifact processing states and event stream support
+
+## Choose The Boundary
+
+- `src/adapters`: upload transport, signed URL calls, artifact downloads.
+- `src/features/<feature>`: validation, upload workflow, and artifact query or mutation state.
+- `src/components/shared`: reusable file picker, progress list, and preview shell.
+- `src/shared`: size formatting, safe filename helpers, and error normalization.
+
+## Do This In Order
+
+1. Keep file validation explicit before upload starts.
+2. Model selection, uploading, processing, ready, and failure as separate states.
+3. Preserve upload ID, artifact ID, processing job ID, and last event ID when readiness is asynchronous.
+4. Treat upload completion and artifact readiness as separate truths.
+5. Allow retry or refresh without duplicating uploads where possible.
+
+## Copy This Shape
+
+```ts
+type ArtifactStatus =
+  | "selected"
+  | "uploading"
+  | "processing"
+  | "ready"
+  | "failed-validation"
+  | "failed-upload"
+  | "failed-processing";
+```
+
+## Never Do These
+
+- Pretending an artifact is ready immediately after upload when processing is asynchronous.
+- Client-only validation as the only protection.
+- Losing progress and error state on route-local rerenders.
+- Download links without accessible names or file metadata.
+
+## Validate
+
+- Validation, upload, processing, ready, and failure states are visible.
+- Upload cancellation or retry behavior is explicit.
+- Large files and unsupported types fail clearly.
+- Artifact readiness is reconciled from server state.
+
+## Done When
+
+- Upload completion and artifact readiness are modeled separately.
+- Progress and error state survive the owning workflow.
+- Artifact metadata is preserved for retries and reconciliation.
+- Users can understand whether a file is uploaded, processing, ready, or failed.
+
+## Handoff
+
+- Use `askr-api-integration` when signed URLs or artifact APIs are the hard part.
+- Use `askr-error-loading-empty` when the hard part is presenting processing and failure truth.
+- Use `askr-testing-determinism` before closing upload and retry behavior.

package/skills/askr-file-upload-artifacts/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr File Upload Artifacts"
+  short_description: "Handle uploads and artifacts"
+  default_prompt: "Use $askr-file-upload-artifacts to build file workflows."

package/skills/askr-forms-tables-crud/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: askr-forms-tables-crud
+description: Use when building askr CRUD screens, forms, validation, filters, tables, pagination, selection, bulk actions, confirmation dialogs, row actions, resource/query data flow, and feature folder boundaries.
+---
+
+# Askr Forms Tables CRUD
+
+Use this for create, read, update, archive, filter, paginate, and edit workflows. The goal is a predictable split between route composition, feature workflow state, and transport boundaries.
+
+## Inspect First
+
+- The nearest page that owns a table or form.
+- The nearest feature folder for the same domain.
+- The adapter or service that owns transport.
+- Existing tests that cover filtering, submission, or destructive actions.
+
+## Use This When
+
+- You are adding a list, detail, create, edit, archive, or bulk-action flow.
+- You need filters, pagination, selection, or row actions.
+- You need field validation and server validation errors.
+- You need a safe destructive action flow.
+
+## Pick The Owner
+
+- The route or page composes the screen.
+- The feature folder owns filters, form state, table columns, queries, and mutations.
+- The adapter owns fetch, update, archive, and DTO mapping.
+- Shared helpers own cross-cutting formatting and validation helpers when reused.
+
+## Copy This Shape
+
+```text
+src/pages/app/users.tsx
+src/features/users/user-table.tsx
+src/features/users/user-filters.tsx
+src/features/users/user-form.tsx
+src/features/users/users.query.ts
+src/features/users/users.mutation.ts
+src/adapters/users-client.ts
+src/shared/format.ts
+```
+
+Routes compose the screen. Features own domain UI and workflow state. Adapters own transport. Shared helpers own cross-cutting formatting or validation utilities.
+
+## Do This In Order
+
+1. Choose the async owner first: `resource()` for route-owned reads, `createQuery()` for shared keyed reads, and `createMutation()` for writes.
+2. Keep filters, pagination, dialog state, and selected IDs in local `state()` pairs, and read or write each one through its `[getter, setter]` pair.
+3. Keep field validation and submit handling explicit in the feature layer.
+4. Confirm destructive actions before archive or delete.
+5. Refresh or invalidate after create, update, archive, or delete.
+
+## Table Rules
+
+- Use stable row keys, never index keys for records.
+- Put feature-specific columns in the feature folder.
+- Use `selector()` for keyed row selection fanout when the table is large or hot.
+- Provide loading, empty, error, and disabled action states.
+- Keep formatting in `src/shared/format.ts` or a domain feature helper.
+
+## Form Rules
+
+- Keep form state local unless multiple routes need it.
+- Put validation rules in `src/features/<feature>` when domain-specific, or `src/shared` when cross-cutting.
+- Use `@askrjs/ui` form controls for behavior and accessibility.
+- Disable submit while pending and surface field or form errors explicitly.
+
+- API clients in table, form, or generic UI components.
+- Bound live or frequently updating rows so tables and timelines do not churn the whole DOM.
+- Keep filtering, sorting, and pagination state together in the feature workflow instead of scattering it across route files.
+- Business rules in reusable primitives.
+- Hidden destructive actions without confirmation.
+- Duplicated pagination/filter logic across route files.
+- A table component that imports a raw API client and mutates records directly from row actions.
+- A form that shows only a toast on submit failure and never maps field errors back to inputs.
+- Pagination, sorting, and filter state duplicated in multiple route pages.
+
+## Validate
+
+- CRUD ownership boundaries are obvious.
+- Every async path has loading, error, retry, or disabled feedback.
+- Selection, bulk actions, and destructive actions are keyboard reachable.
+- Submit handlers preserve pending state and field or form errors.
+- Record rows use stable keys.
+
+## Done When
+
+- Form, table, mutation, and adapter ownership are separated.
+- Field errors, form errors, pending state, and success state are all visible.
+- Selection, filters, sorting, and destructive actions are keyboard reachable.
+- Rows keep stable identity and large updates do not force whole-list churn.
+
+## Handoff
+
+- Use `askr-query-mutation` when the form or table state becomes shared keyed state across screens.
+- Use `askr-accessibility` when validation, focus, or destructive-action UX is the hard part.
+- Use `askr-testing-determinism` to validate submit, retry, selection, and list identity behavior.

package/skills/askr-forms-tables-crud/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Forms Tables CRUD"
+  short_description: "Build CRUD forms and tables"
+  default_prompt: "Use $askr-forms-tables-crud to build a CRUD workflow in askr."

package/skills/askr-mental-model/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: askr-mental-model
+description: Use when an AI agent or developer needs the canonical Askr mental model, including what Askr is, what it is not, how core primitives fit together, and which React-style assumptions must be rejected.
+---
+
+# Askr Mental Model
+
+Use this before building or reviewing Askr code when primitive choice is unclear. This skill exists to keep agents on the native Askr path and off React-shaped defaults.
+
+## Use This When
+
+- Primitive choice is unclear.
+- The task looks like React, hooks, or a generic SPA by default.
+- You need to decide who owns local state, async reads, or writes.
+- You need one obvious Askr-native shape before editing.
+
+## Inspect First
+
+- `AGENTS.md` when it exists
+- `src/main.tsx`
+- The nearest route file and layout file
+- The nearest existing feature that solves a similar problem
+- Existing tests for the touched surface
+
+## What Askr Expects
+
+- Route-first ownership.
+- Synchronous route components.
+- Explicit runtime primitives for state, derived state, lifecycle-owned async work, shared server state, and writes.
+- Honest UI for loading, empty, error, stale, and pending-write states.
+
+## What Askr Is Not
+
+- Not a React hooks runtime.
+- Not a place to default to `useEffect` data loading.
+- Not a reason to add React Router, TanStack Query, or a global state library first.
+- Not a place to clone solved `Button`, `Card`, `Sidebar`, `EmptyState`, or shell primitives before checking the existing theme and UI layers.
+
+## Pick The Primitive
+
+- Local mutable UI state: use `state()` as a `[getter, setter]` pair.
+- Computed value from reactive reads: use `derive()`.
+- One source fans out to many keyed readers: use `selector()`.
+- One route or container owns an async read lifecycle: use `resource()`.
+- Shared keyed server state used across screens: use `createQuery()`.
+- Writes with pending, error, and reconciliation state: use `createMutation()`.
+- Keyed or dynamic list identity matters: use `For`.
+
+## Copy This Shape
+
+```tsx
+import { derive, selector, state } from "@askrjs/askr";
+import { For } from "@askrjs/askr/control";
+
+const [selectedId, setSelectedId] = state<string | null>(null);
+const isSelected = selector(selectedId);
+const items = derive(() => [
+  { id: "queued", label: "Queued" },
+  { id: "running", label: "Running" },
+  { id: "done", label: "Done" },
+]);
+
+export default function RunFilterBar() {
+  return (
+    <nav aria-label="Run status filters">
+      <For each={items()} by={(item) => item.id}>
+        {(item) => (
+          <button
+            type="button"
+            aria-pressed={isSelected(item.id)}
+            onClick={() => setSelectedId(item.id)}
+          >
+            {item.label}
+          </button>
+        )}
+      </For>
+    </nav>
+  );
+}
+```
+
+## Reject These Shapes
+
+- React imports or hook-shaped state as the default solution.
+- Effect-driven loading when the UI depends on the async result.
+- Treating getters like plain values instead of callable reads.
+- Creating runtime helpers conditionally.
+- Defaulting to `.map()` for large or dynamic keyed lists where `For` should own identity.
+- Hiding data transport, mapping, and mutations inside pages or presentational components.
+
+## Validate
+
+- Primitive choice is explainable in one sentence.
+- Route components remain synchronous.
+- Keyed UI uses stable IDs.
+- No React runtime imports or hook defaults slipped in.
+- Async state truth is explicit where the user can observe it.
+
+## Done When
+
+- The code reads like Askr, not like translated React.
+- No invented primitives or parallel state layers were added.
+- The next narrower skill is obvious from the changed surface.
+
+## Handoff
+
+- Use `askr-routing-layouts` when the next step is route ownership or shell structure.
+- Use `askr-resources-data` or `askr-query-mutation` when the next step is async ownership.
+- Use `askr-runtime-reactivity` when the next step is local state or keyed rendering behavior.

package/skills/askr-mental-model/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Mental Model"
+  short_description: "Learn the canonical Askr runtime model"
+  default_prompt: "Use $askr-mental-model before building or reviewing Askr application code."

package/skills/askr-migration-react/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: askr-migration-react
+description: Use when translating React-shaped code, habits, or component designs into idiomatic Askr, including replacing useState/useEffect patterns, JSX assumptions, data fetching, routing, context, component APIs, and UI primitive choices.
+---
+
+# Askr Migration React
+
+Use this only when a task, sample, or codebase slice is React-shaped and must be translated into idiomatic Askr. It is a transition skill, not a default entrypoint for normal Askr feature work.
+
+## Use This When
+
+- The input code or prompt uses React hooks, React Router, or React-only UI assumptions.
+- A generated design mirrors React patterns that need translation before implementation.
+- A migration task needs native Askr ownership for state, async work, routing, or primitives.
+- The fastest path is to convert a known React shape instead of designing from scratch.
+
+## Inspect First
+
+- The current app's Askr imports and component patterns
+- The route tree and feature boundaries already present in the repo
+- The React-shaped state, async, routing, and primitive assumptions you are replacing
+
+## Choose The Replacement
+
+- React `useState` -> Askr `state()` as a `[getter, setter]` pair.
+- React `useMemo` -> Askr `derive()` when a reactive computation is needed.
+- React `useEffect` data loading -> Askr `resource()` or `createQuery()` based on ownership.
+- React Router component routes -> Askr route registration with `group()`, `page()`, `route()`, and `fallback()`.
+- React context -> Askr `defineScope()` and `readScope()`.
+- React keyed list `.map` -> `For` when identity or dynamic list updates matter.
+
+## Do This In Order
+
+1. Identify whether the React-shaped code is really local state, shared data, routing, context, or primitive behavior.
+2. Remove React imports and hook assumptions before translating line by line.
+3. Replace state, async, routing, and context with the owning Askr primitives.
+4. Move feature logic to the correct route, feature, adapter, or shared boundary.
+5. Replace React-only UI libraries with Askr-compatible primitives when behavior matters.
+6. Validate call order, async truth, and route registration before closing the migration.
+
+## Copy This Shape
+
+```tsx
+import { state } from "@askrjs/askr";
+import { resource } from "@askrjs/askr/resources";
+
+const [open, setOpen] = state(false);
+const user = resource(({ signal }) => loadUser(id, { signal }), [id]);
+
+<button onClick={() => setOpen((value) => !value)}>{open() ? "Close" : "Open"}</button>;
+```
+
+## Never Do These
+
+- Importing React hooks or React runtime helpers.
+- Treating state getters like values instead of functions.
+- Porting React Router route components directly.
+- Hiding async work in effects when the UI depends on it.
+- Assuming third-party React component packages are compatible.
+
+## Validate
+
+- No React imports remain unless the project intentionally embeds React separately.
+- Runtime helper call order is stable.
+- Async work has cancellation and visible loading or error states.
+- Routing uses Askr route registration.
+- Interactive UI uses Askr-compatible primitives.
+
+## Done When
+
+- The translated code reads like Askr instead of line-by-line React porting.
+- State, async work, routing, and context use native Askr ownership.
+- Feature logic sits in the right file boundaries.
+- Remaining UI assumptions are compatible with the app's existing primitives.
+
+## Handoff
+
+- Use `askr-mental-model` when primitive choice is still unclear.
+- Use `askr-project-structure` when the migration requires moving files or ownership boundaries.
+- Use `askr-query-mutation` or `askr-resources-data` when async ownership is the real blocker.
+- Use `askr-testing-determinism` before closing migrated behavior.

package/skills/askr-migration-react/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Migration React"
+  short_description: "Translate React habits to askr"
+  default_prompt: "Use $askr-migration-react to convert React-shaped code into askr."

package/skills/askr-observability-debugging/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: askr-observability-debugging
+description: Use when adding Askr observability, debugging, structured logs, request IDs, trace IDs, query and mutation diagnostics, event-sourced replay context, agent-run audit trails, and dev-only diagnostics.
+---
+
+# Askr Observability Debugging
+
+Use this when failures must be explainable to users, developers, or operators. The goal is preserved correlation data, safe user-facing errors, and diagnosable stale or event-driven failures.
+
+## Use This When
+
+- A failure needs request, trace, command, run, or event correlation.
+- You need safe user-visible error copy plus deeper operator diagnostics.
+- The UI depends on stale-state or eventual-consistency diagnostics.
+- An agent workflow, realtime flow, or write path needs audit-friendly tracing.
+
+## Inspect First
+
+- Existing error normalization and logging helpers in `src/shared`
+- API request and response metadata available from adapters
+- Query and mutation consistency or error states
+- Agent run IDs, command IDs, event IDs, and audit requirements
+
+## Preserve These IDs
+
+- Request ID or trace ID.
+- User, session, or workspace ID where safe.
+- Command ID, idempotency key, aggregate ID, version, event ID, or projection cursor.
+- Query key and invalidation prefix.
+- Run ID, tool call ID, approval ID, and artifact ID for agentic workflows.
+
+## Do This In Order
+
+1. Preserve correlation metadata at the adapter boundary.
+2. Normalize errors into a user-safe message plus structured diagnostics.
+3. Show safe copy to users and deeper context only in logs or dev-only panels.
+4. Preserve stale-state, projection, or replay context when eventual consistency matters.
+5. Add focused tests for duplicate-event, stale-state, or correlation behavior when the flow depends on it.
+
+## Copy This Shape
+
+```ts
+const normalized = normalizeApiError(error, {
+  requestId,
+  commandId,
+  eventId,
+  queryKey: "accounts:list",
+});
+
+logError("accounts.refresh.failed", normalized.diagnostics);
+return {
+  message: "Unable to refresh accounts.",
+  diagnostics: normalized.diagnostics,
+};
+```
+
+## Never Do These
+
+- Swallowing errors in async handlers.
+- Console-only diagnostics for production-critical flows.
+- Showing raw stack traces or transport payloads to users.
+- Losing correlation IDs between adapters, features, and UI errors.
+- Logging private prompts, tokens, or sensitive request bodies to preserve debugging context.
+
+## Validate
+
+- Errors include user-safe copy and developer-useful context.
+- Eventual-consistency states are diagnosable.
+- Agent workflows have audit-friendly run and event IDs.
+- Logs do not contain secrets or private prompts.
+
+## Done When
+
+- User-facing failures stay safe and intelligible.
+- Operators have enough correlation data to trace the issue.
+- Stale or event-sourced failures are diagnosable separately from command success.
+- No logs or diagnostics leak secrets or private prompts.
+
+## Handoff
+
+- Use `askr-api-integration` when metadata is being dropped before it reaches the feature layer.
+- Use `askr-agent-workflows` when run IDs, tool calls, approvals, or artifacts need user-facing traceability.
+- Use `askr-testing-determinism` to prove duplicate-event, stale-state, or error-correlation behavior.

package/skills/askr-observability-debugging/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Observability Debugging"
+  short_description: "Trace and debug Askr workflows"
+  default_prompt: "Use $askr-observability-debugging to add diagnostics."

package/skills/askr-project-structure/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: askr-project-structure
+description: Use when deciding where Askr app files belong, naming components, separating route-first pages, layouts, features, shared helpers, adapters, reusable UI, tests, and package-owned responsibilities.
+---
+
+# Askr Project Structure
+
+Use this before creating, moving, or splitting files. The goal is one obvious owner per file and no parallel architecture.
+
+## Use This When
+
+- You need to add a new file.
+- You are tempted to put logic in a page because it is nearby.
+- The repo already has routes, features, adapters, or shared helpers and you need the right owner.
+- You want to avoid duplicate structures for the same concern.
+
+## Inspect First
+
+- The existing route registry and nearest `_layout.tsx` owner.
+- The nearest existing feature folder for the same domain.
+- The nearest adapter, shared helper, and reusable component folder.
+- Existing tests for the same surface.
+
+## Keep The Existing App Shape
+
+- If the repo uses `src/pages/**/_routes.tsx`, keep using it.
+- If the repo uses `src/routes/*`, keep using it.
+- If the repo uses `src/shared`, keep shared helpers there.
+- If the repo uses `src/lib` for shared helpers, keep using it.
+- Do not create a second route tree, a second shared layer, or a second feature layout because one file looked easier.
+
+## Pick The Owner
+
+- URL reachability: nearest route registry file.
+- Shell chrome or persistent branch UI: matching `_layout.tsx`.
+- Domain workflow, queries, mutations, and feature UI: `src/features/<feature>/`.
+- Reusable display-only pieces: the repo's shared components folder.
+- Cross-cutting helpers such as formatting or parsing: the repo's shared helper folder.
+- Generated clients, raw fetch wrappers, and DTO mapping: `src/adapters/`.
+- Visual styling and tokens: CSS or theme layer, not runtime logic.
+
+## Copy This Shape
+
+```text
+src/pages/app/billing.tsx          # route-owned page shell
+src/features/billing/billing-form.tsx
+src/features/billing/billing.query.ts
+src/adapters/billing-client.ts
+src/shared/format-money.ts
+```
+
+## Reject These Shapes
+
+- `src/pages/app/billing.tsx` importing a generated API client directly.
+- `src/components/shared/billing-table.tsx` owning billing mutations and route redirects.
+- `src/shared/billing.tsx` containing JSX and transport code together.
+- API clients in components or UI primitives.
+- Business logic or transport code in `src/pages`.
+- JSX in `src/shared` or `src/adapters`.
+- Duplicate shells across pages.
+- One component that owns routing, fetching, mutation, and styling.
+- Parallel abstractions for a concern Askr already owns.
+
+## Validate
+
+- Another agent could predict where the file belongs.
+- No page directly owns raw transport or DTO mapping.
+- No JSX leaked into adapters or shared helper files.
+- New folders match the existing repo shape instead of creating a second one.
+
+## Done When
+
+- No duplicate structure was introduced for the same concern.
+
+## Handoff
+
+- Use `askr-routing-layouts` when the hard part is URL ownership.
+- Use `askr-resources-data` or `askr-query-mutation` when the hard part is async ownership.
+- Use `askr-testing-determinism` once ownership is settled and you need validation.

package/skills/askr-project-structure/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Project Structure"
+  short_description: "Place Askr files in the right layer"
+  default_prompt: "Use $askr-project-structure to decide where Askr app files belong."

package/skills/askr-query-mutation/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: askr-query-mutation
+description: Use when modeling shared server state in Askr with createQuery, createMutation, invalidate, service boundaries, consistency states, pending writes, cache keys, event-sourced read models, and explicit read/write coordination.
+---
+
+# Askr Query Mutation
+
+Use this for shared keyed reads and writes that must coordinate across screens or survive beyond one render. The goal is deliberate keys, narrow invalidation, and truthful write reconciliation.
+
+## Use This When
+
+- Multiple screens need the same keyed server state.
+- A write must invalidate or reconcile shared reads.
+- The UI needs pending, error, stale, or pending-write truth after a mutation.
+- Event-sourced or eventually consistent data needs explicit reconciliation.
+
+## Inspect First
+
+- Existing query keys and invalidation prefixes.
+- The nearest feature owner for the data.
+- The adapter or service boundary that should receive `signal`.
+- Existing stale, syncing, or pending-write UI on the same surface.
+
+## Pick The Data Owner First
+
+- One route or container owns the read and no other screen shares it: use `askr-resources-data`.
+- Shared keyed read that multiple screens can refresh or invalidate: use `createQuery()`.
+- Write with visible pending, error, result, and invalidation behavior: use `createMutation()`.
+
+## Do This In Order
+
+1. Design a stable, prefix-friendly query key.
+2. Keep fetch and mutation transport in an adapter or service boundary.
+3. Use `createQuery()` for the shared read and `createMutation()` for the write.
+4. Invalidate only the affected key or prefix after success.
+5. Preserve version, event ID, cursor, or command metadata when the UI must reason about projection lag.
+
+## Copy This Shape
+
+```ts
+import { createQuery, invalidate } from "@askrjs/askr/data";
+
+const user = createQuery({
+  key: `user:${id}`,
+  fetch: ({ signal }) => userService.getUser(id, { signal }),
+});
+
+await user.refresh();
+invalidate("user:");
+```
+
+## Mutation Shape
+
+```ts
+import { createMutation } from "@askrjs/askr/data";
+
+const saveUser = createMutation({
+  action: (input, { signal }) => userService.updateUser(input, { signal }),
+  affects: (input) => [`user:${input.id}`, "users:"],
+  afterSuccess: "invalidate",
+});
+
+await saveUser.execute({ id, name });
+```
+
+- Only use optimistic updates when rollback or refetch behavior is explicit.
+- If the backend is event-sourced, prefer truthful `pending-write` or `syncing` UI over pretending the projection already caught up.
+- Keep optimistic local intent separate from confirmed read-model state.
+
+## Event-Sourced Consistency
+
+Use this pattern when writes append events and reads come from projections:
+
+- Command success means the write was accepted, not necessarily that every read model is caught up.
+- Include command ID, aggregate ID, expected version, observed version, event ID, or projection cursor in mutation results when the backend exposes them.
+- Use `affects` and `afterSuccess: 'invalidate'` to mark affected queries as `pending-write` and refresh them.
+- Keep the old query data visible while `consistency` is `pending-write`, `refreshing`, or `stale`.
+- On stream reconnect or cursor gaps, invalidate the affected query prefix instead of replaying uncertain local state.
+- Use `isConsistent` to compare returned read data against expected versions or event IDs.
+- Use `reconcile` to retry while a projection is behind, with user-visible stale/syncing feedback.
+
+```ts
+const account = createQuery({
+  key: `account:${id}`,
+  fetch: ({ signal }) => accountsService.getAccount(id, { signal }),
+  isConsistent: (data) => data.version >= expectedVersion(),
+  reconcile: () => true,
+});
+```
+
+- Fetching directly in many leaf components.
+- Hiding writes inside presentational UI.
+- Cache keys that cannot be invalidated predictably.
+- Generic query clients or global state abstractions unless the app already owns one.
+- Optimistic updates without rollback or refetch.
+- Treating write acknowledgement as read-model convergence in event-sourced systems.
+- Cache keys that mix route-local UI state with shared server-state identity.
+
+## Validate
+
+- Query keys are stable and prefix-friendly.
+- `signal` reaches the service boundary.
+- Mutation pending and error states are visible outside the button that triggered them.
+- Success invalidates only the affected read model.
+- Event or version metadata is preserved when the UI needs to reason about catch-up.
+
+## Done When
+
+- The feature did not grow a second cache or state layer.
+
+## Handoff
+
+- Use `askr-api-integration` when DTO mapping or transport details are the real blocker.
+- Use `askr-error-loading-empty` when the hard part is presenting stale, syncing, or retry truth.
+- Use `askr-realtime-streaming` when queries must reconcile with live events.