@askrjs/cli 0.0.2

package/skills/askr-query-mutation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Query Mutation"
+  short_description: "Coordinate shared read/write state"
+  default_prompt: "Use $askr-query-mutation to model shared server state and writes."

package/skills/askr-realtime-streaming/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: askr-realtime-streaming
+description: Use when building Askr realtime UX with SSE, WebSocket, event streams, reconnects, cursors, cancellation, backpressure-aware UI, optimistic updates, projection lag, and event-sourced state.
+---
+
+# Askr Realtime Streaming
+
+Use this for live data, event streams, and projection-driven UI. The goal is one clear stream owner, safe reconnect behavior, and bounded DOM and memory cost.
+
+## Use This When
+
+- You need SSE, WebSocket, or long-lived event streaming.
+- The UI depends on reconnect, cursor, or projection-lag behavior.
+- A timeline, operator log, or live table needs bounded updates.
+- You need to reconcile stream events with queries or feature-owned state.
+
+## Inspect First
+
+- Adapter support for SSE, WebSocket, polling, or long-running requests
+- Event schema: event ID, sequence, aggregate ID, type, timestamp, and payload
+- Query keys and mutation invalidation affected by streamed events
+- Reconnect and resume requirements
+
+## Do This In Order
+
+1. Own the stream lifecycle in a route or feature container, not a leaf row or list item.
+2. Preserve `lastEventId` or cursor for reconnect.
+3. Apply events idempotently by event ID or sequence.
+4. Detect gaps and refetch or invalidate the affected read model instead of guessing.
+5. Bound long-running buffers so memory and DOM cost stay predictable.
+6. Show `connected`, `reconnecting`, `stale`, or `failed` state when freshness matters.
+
+## Copy This Shape
+
+```ts
+const MAX_EVENTS = 200;
+
+function applyEvent(nextEvent: StreamEvent) {
+  setEvents((current) => {
+    if (current.some((event) => event.id === nextEvent.id)) {
+      return current;
+    }
+
+    return [...current, nextEvent].slice(-MAX_EVENTS);
+  });
+  setLastEventId(nextEvent.id);
+}
+```
+
+## Never Do These
+
+- Assuming streamed events arrive exactly once or in order.
+- Clearing the screen during reconnect.
+- Unbounded in-memory event lists.
+- Mixing transport code into pages or components.
+- Treating command success as projection success.
+
+## Validate
+
+- Reconnect resumes from a cursor or falls back to refetch.
+- Duplicate and out-of-order events are safe.
+- Projection lag has visible UI.
+- Stream teardown happens on navigation or unmount.
+
+## Done When
+
+- Stream ownership is clear and not buried in leaf components.
+- Reconnect, duplicate, gap, and teardown paths are handled.
+- Memory and DOM cost stay bounded for long-running screens.
+- Projection success is never inferred from command success alone.
+
+## Handoff
+
+- Use `askr-query-mutation` when stream events reconcile shared queries.
+- Use `askr-api-integration` when cursor, event ID, or transport shape is unclear.
+- Use `askr-observability-debugging` when reconnect failures or duplicate events need operator diagnostics.

package/skills/askr-realtime-streaming/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Realtime Streaming"
+  short_description: "Build realtime evented UX"
+  default_prompt: "Use $askr-realtime-streaming to build realtime Askr UI."

package/skills/askr-resources-data/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: askr-resources-data
+description: Use when loading lifecycle-aware async data in Askr with resource, cancellation signals, pending/error/value states, refresh behavior, route/container ownership, consistency-aware refreshes, and async anti-pattern cleanup.
+---
+
+# Askr Resources Data
+
+Use this when one route or feature container owns an async read lifecycle. The goal is one clear async owner, explicit cancellation, and truthful refresh behavior.
+
+## Use This When
+
+- One route or feature container owns the read.
+- The read should cancel on unmount, navigation, or dependency change.
+- Children need plain data props instead of owning their own fetches.
+- The data does not need to live as shared keyed state across screens.
+
+## Inspect First
+
+- The nearest route or feature container that already owns async work.
+- The adapter or service that should receive `signal`.
+- Existing refresh or retry controls for the same surface.
+- Existing tests that cover load, retry, or cancellation behavior.
+
+## Use `resource()` Only When
+
+- The read belongs to one owner in one route or feature container.
+- The owner should cancel stale requests automatically.
+- The screen can keep old data during refresh when safe.
+
+If the same keyed server state must coordinate across screens, stop and use `askr-query-mutation` instead.
+
+## Do This In Order
+
+1. Put the `resource()` call in the smallest route or feature container that owns the data.
+2. Pass `signal` into the adapter or fetch layer.
+3. Keep route handlers synchronous.
+4. Pass `value`, `pending`, `error`, and `refresh()` downward as plain props.
+5. Keep stale data visible during refresh unless that would be unsafe.
+
+## Copy This Shape
+
+```tsx
+import { resource } from "@askrjs/askr/resources";
+
+function UserCard({ id }: { id: string }) {
+  const user = resource(
+    async ({ signal }) => {
+      const response = await fetch(`/api/users/${id}`, { signal });
+      return response.json();
+    },
+    [id],
+  );
+
+  if (user.pending || !user.value) return <p>Loading...</p>;
+  if (user.error) return <p role="alert">Unable to load user.</p>;
+  return <p>{user.value.name}</p>;
+}
+```
+
+## Owner Pattern
+
+```tsx
+function AccountsPage() {
+  const accounts = resource(({ signal }) => loadAccounts({ signal }), []);
+
+  return (
+    <AccountsScreen
+      accounts={accounts.value}
+      pending={accounts.pending}
+      error={accounts.error}
+      onRefresh={() => accounts.refresh()}
+    />
+  );
+}
+```
+
+- Async route components.
+- `useEffect`-style data loading.
+- Custom cancellation tokens when `signal` exists.
+- Hidden loading or error paths.
+- Fetching in generic UI primitives.
+- Route-local async ownership that should actually be shared keyed state.
+
+## Validate
+
+- The async owner is the smallest container that needs the data.
+- `signal` reaches the cancellable work.
+- Loading, empty, error, and retry paths are explicit.
+- Route handlers stay synchronous.
+- Refresh behavior is honest about stale data and projection lag.
+
+## Done When
+
+- The screen did not grow a parallel shared-state layer.
+
+## Handoff
+
+- Use `askr-query-mutation` when this data must become shared keyed state.
+- Use `askr-error-loading-empty` when the hard part is truthful state representation.
+- Use `askr-testing-determinism` to validate cancellation, retry, and refresh behavior.

package/skills/askr-resources-data/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Resources Data"
+  short_description: "Load cancellable lifecycle data"
+  default_prompt: "Use $askr-resources-data to load async data with resource()."

package/skills/askr-routing-layouts/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: askr-routing-layouts
+description: Use when defining Askr routes, route groups, page shells, index routes, fallback routes, navigation, auth requirements, route loaders, layout boundaries, or SPA/SSR/SSG shared route trees.
+---
+
+# Askr Routing Layouts
+
+Use this for route registration, shell ownership, route metadata, and navigation. The goal is one obvious route tree that is registered before boot.
+
+## Use This When
+
+- You are adding, moving, or protecting a route.
+- You are changing a shell or layout boundary.
+- You need to attach an auth requirement or route policy.
+- You need to add route-aware navigation.
+
+## Inspect First
+
+- `src/main.tsx`
+- The app's route registry file
+- The nearest branch route file and `_layout.tsx`
+- Existing navigation components for the same branch
+- Tests that already cover routing or layout retention
+
+## Choose The Owner
+
+- `group()` for inherited layout, auth requirements, or policies without a path segment.
+- `page()` for a pathful shell that renders child route content.
+- `route()` for a leaf route.
+- `index()` only inside a `page()` scope.
+- `fallback()` at the root or inside a `page()` scope that owns the fallback.
+
+## Do This In Order
+
+1. Register the route in the existing route tree before app boot.
+2. Put auth requirements and policies on the narrowest route or group that owns them.
+3. Keep route components synchronous and put async work inside route-owned components or features.
+4. Keep navigation in `Link`, `navigate()`, and `currentRoute()` instead of local copies of route state.
+
+## Copy This Shape
+
+```tsx
+import { requireUser } from "@askrjs/auth";
+import { createRouteRegistry, fallback, group } from "@askrjs/askr/router";
+
+export const pageRegistry = createRouteRegistry(() => {
+  group({ layout: RootLayout }, () => {
+    group({ layout: PublicLayout }, () => {
+      registerPublicRoutes();
+    });
+    group({ layout: AppLayout, auth: requireUser() }, () => {
+      registerAppRoutes();
+    });
+    fallback(NotFoundPage);
+  });
+});
+```
+
+## Nested Example
+
+```tsx
+import { requirePermission } from "@askrjs/auth";
+import { fallback, index, page, route } from "@askrjs/askr/router";
+
+export function registerWorkspaceRoutes(): void {
+  page("/workspaces/{workspaceId}", WorkspaceLayout, () => {
+    index(WorkspaceOverviewPage);
+    route("settings", WorkspaceSettingsPage, {
+      auth: requirePermission("workspace.manage"),
+    });
+    route("members", WorkspaceMembersPage, {
+      auth: requirePermission("workspace.read"),
+    });
+    fallback(WorkspaceNotFoundPage);
+  });
+}
+```
+
+Use relative child paths inside `page()`. Put requirements and policies on the narrowest route or group that owns them.
+
+## Never Do These
+
+- Registering routes during render.
+- Calling `route()` inside components; use `currentRoute()` there.
+- Nesting `page()` inside `page()`.
+- Absolute child route paths inside `page()`.
+- Treating `group()` as a fallback scope.
+- Putting theme styling decisions in route registration.
+- Building a second router or page-local auth gate when route metadata already owns it.
+
+## Validate
+
+- The route tree is registered before boot.
+- Shared route behavior lives in `group()` instead of repeated route-local checks.
+- Child routes under `page()` use relative paths.
+- Fallback scope is explicit.
+- Navigation uses router primitives instead of local state copies.
+
+## Done When
+
+- The route tree is still the only route tree in the app.
+
+## Handoff
+
+- Use `askr-auth-access` when the next step is session or permission behavior.
+- Use `askr-project-structure` when routing work also adds new files.
+- Use `askr-testing-determinism` to validate route identity, fallback behavior, and layout retention.

package/skills/askr-routing-layouts/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Routing Layouts"
+  short_description: "Define Askr routes and shells"
+  default_prompt: "Use $askr-routing-layouts to add routes, layouts, and navigation."

package/skills/askr-runtime-reactivity/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: askr-runtime-reactivity
+description: Use when writing askr reactive runtime code with state, derive, selector, context, JSX control flow, stable call order, deterministic event handling, or render lifecycle rules.
+---
+
+# Askr Runtime Reactivity
+
+Use this when local state, derived values, keyed identity, or runtime determinism matters. The goal is stable helper call order and correct primitive use.
+
+## Use This When
+
+- You are adding local UI state.
+- You need a computed value from reactive reads.
+- You are rendering keyed lists, selections, or filters.
+- You need to keep call order stable across renders.
+
+## Inspect First
+
+- The nearest existing component with similar state or list behavior.
+- Existing tests that already cover toggles, selection, or filtering.
+- The nearest feature owner if local state may need to become shared later.
+
+## Pick The Primitive
+
+- Local mutable value: `state()` returns a `[getter, setter]` pair.
+- Computed value from reactive reads: `derive()`.
+- One reactive source fans out to many keyed readers: `selector()`.
+- Cross-tree shared value: `defineScope()` and `readScope()`.
+- Keyed or identity-sensitive list: `For`.
+
+## Copy This Shape
+
+```tsx
+import { derive, selector, state } from "@askrjs/askr";
+import { For, Show } from "@askrjs/askr/control";
+
+const [count, setCount] = state(0);
+const [selectedId, setSelectedId] = state<number | null>(null);
+const doubled = derive(() => count() * 2);
+const isSelected = selector(selectedId);
+```
+
+`state()` returns a `[getter, setter]` pair. Read with `getter()` and update with `setter(...)`.
+
+## Determinism Rules
+
+- Do not call `state`, `derive`, `selector`, `resource`, query, or mutation helpers conditionally.
+- Do not mutate state during render.
+- Batch related updates in the event handler that owns the user action.
+- Preserve stable keys in `For` for rows and reorderable lists.
+
+## Reject This Shape
+
+```tsx
+function BadList({ rows }) {
+  if (rows.length > 0) {
+    const [selected, setSelected] = state(rows[0].id);
+    return rows.map((row, index) => (
+      <button key={index} onClick={() => setSelected(row.id)}>
+        {selected === row.id ? "Selected" : row.label}
+      </button>
+    ));
+  }
+
+  return null;
+}
+```
+
+Reject this shape. It creates state conditionally, treats getter/setter values like plain variables, and uses index keys where stable identity matters.
+
+- Reading a getter without calling it.
+- React hooks or `useState` in Askr app code.
+- Recreating selectors in row components.
+- Index keys for data with stable IDs.
+- Derived state that performs side effects.
+
+## Validate
+
+- Runtime helpers are top-level and unconditional.
+- Getter calls are explicit.
+- Lists have stable identity.
+- Existing or new tests cover the state change that matters.
+
+## Done When
+
+- No React-style state shape or conditional helper creation slipped in.
+
+## Handoff
+
+- Use `askr-query-mutation` when the next step is shared keyed state.
+- Use `askr-resources-data` when the next step is async lifecycle ownership.
+- Use `askr-testing-determinism` before closing runtime-sensitive changes.

package/skills/askr-runtime-reactivity/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Runtime Reactivity"
+  short_description: "Write deterministic Askr state code"
+  default_prompt: "Use $askr-runtime-reactivity to write deterministic Askr state and control flow."

package/skills/askr-ssr-ssg/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: askr-ssr-ssg
+description: Use when building askr server-rendered or static-generated apps, working with SSR/SSG entrypoints, route manifests, static generation configs, hydration-safe rendering, resource constraints, and render output verification.
+---
+
+# Askr SSR SSG
+
+Use this when the app renders outside the browser or produces static output. The goal is one shared route tree, environment-safe render paths, and hydration-safe output.
+
+## Inspect First
+
+- `src/main.tsx`
+- The shared route registry
+- SSR entry files such as `server.ts` or `entry-server.tsx`
+- SSG files such as `ssg.config.ts` or `ssg-build.ts`
+- Existing build and preview scripts in `package.json`
+
+## Use This When
+
+- You are adding SSR or SSG routes.
+- You need parameterized static entries.
+- You need to keep browser-only code out of server render paths.
+- You need to verify hydration safety after changing render behavior.
+
+## Do This In Order
+
+1. Keep the route tree shared across browser, server, and static output where possible.
+2. Register routes at module load before boot or render.
+3. Keep render paths deterministic and environment-safe.
+4. Use route `entries` or the template's static config for parameterized SSG paths.
+5. Build and preview after changes that cross the render boundary.
+
+## Copy This Shape
+
+```ts
+registerRoutes(() => {
+  page("/docs/{slug}", DocsPage, {
+    entries: async () => [{ slug: "getting-started" }, { slug: "routing" }],
+  });
+});
+```
+
+## Never Do These
+
+- Async components in render paths.
+- Route registration that depends on request-time mutation.
+- Browser-only globals in server or static render paths without guards.
+- Divergent route trees for client, server, and static output.
+- Random values or time reads that change initial markup across server and client.
+
+## Static Generation Pattern
+
+```bash
+npx @askrjs/cli create ssg my-site
+npm run build
+npx @askrjs/cli ssg --config ./ssg.config.ts --output ./dist/static
+```
+
+## Validate
+
+- SSR or SSG build output is deterministic for the same inputs.
+- Hydration has no structural mismatch warnings.
+- Generated static routes cover expected params.
+- Browser preview still navigates correctly after hydration.
+
+## Done When
+
+- The same route tree still owns navigation across environments.
+- Server and static render paths are environment-safe.
+- Parameterized routes have explicit static coverage where needed.
+- Build and preview prove the render boundary still works.
+
+## Handoff
+
+- Use `askr-routing-layouts` when the hard part is route ownership.
+- Use `askr-testing-determinism` when hydration, preview, or build verification is the real blocker.

package/skills/askr-ssr-ssg/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr SSR SSG"
+  short_description: "Render askr on server or static"
+  default_prompt: "Use $askr-ssr-ssg to build SSR or static Askr output."

package/skills/askr-testing-determinism/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: askr-testing-determinism
+description: Use when testing Askr apps, validating deterministic runtime behavior, writing jsdom or browser tests, checking accessibility, cleanup, route behavior, resources, queries, mutations, keyed lists, and performance-sensitive UI.
+---
+
+# Askr Testing Determinism
+
+Use this when choosing or running validation for Askr work. The goal is the narrowest executable check that proves the changed contract.
+
+## Use This When
+
+- You changed route behavior, state behavior, async ownership, or user-visible UI.
+- You need to decide which test level is correct.
+- You need objective done criteria before closing a task.
+- You need to avoid ending on diff review alone.
+
+## Inspect First
+
+- Existing tests nearest to the changed files.
+- The repo's test scripts in `package.json`.
+- Existing browser or jsdom coverage for similar behavior.
+- Any known failing test that already describes the bug.
+
+## Pick The Smallest Useful Check
+
+- Unit tests: pure helpers, formatters, validators, route metadata, data transforms.
+- jsdom tests: runtime state, resource behavior, route rendering, component logic.
+- Browser tests: focus, keyboard behavior, overlays, layout, hydration, visual regressions, performance-sensitive flows.
+- Type tests: public API and component prop contracts.
+- Benchmarks: hot paths, keyed lists, large tables, router matching, hydration.
+
+## Validate In This Order
+
+1. The narrowest failing or behavior-scoped test for the slice you changed.
+2. The nearest type check or package check.
+3. Build or template-specific checks when boot, routing, SSR, SSG, or packaging changed.
+4. Manual runtime verification for user-visible async, focus, overflow, or stale-state behavior when tests do not already cover it.
+
+## Determinism Targets
+
+- Event ordering and batched updates.
+- Stable call order for runtime helpers.
+- Keyed DOM identity during list updates.
+- No partial DOM commit after render failure.
+- Async cancellation on navigation or unmount.
+- Route identity and layout retention across navigation.
+
+## Patterns
+
+- Clean up mounted apps with `cleanupApp(root)` when tests mount an app.
+- Prefer user-visible assertions over implementation detail checks.
+- For `resource()`, cover pending, success, error, refresh, and cancellation when relevant.
+- For `@askrjs/ui`, cover keyboard and ARIA behavior.
+- For themes, include computed style and overflow checks where visual contracts matter.
+
+- Tests that depend on uncontrolled timers or random data.
+- Snapshot-only coverage for interactive behavior.
+- Browser behavior tested only in jsdom.
+- Performance changes without a focused benchmark or regression test.
+
+## Validate The Test Itself
+
+- The smallest meaningful test covers the changed contract.
+- The chosen test level matches the behavior under change.
+- Async checks wait for visible state instead of sleeping blindly.
+- The repo's existing scripts are used before inventing new ones.
+
+## Done When
+
+- Diff review was not used as the only proof when an executable check existed.
+
+## Handoff
+
+- Use `askr-accessibility` when browser coverage reveals focus or announcement issues.
+- Use `askr-observability-debugging` when tests expose stale-state or correlation failures.

package/skills/askr-testing-determinism/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Testing Determinism"
+  short_description: "Test deterministic Askr behavior"
+  default_prompt: "Use $askr-testing-determinism to test Askr runtime and UI behavior."

package/skills/askr-theming/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: askr-theming
+description: Use when styling Askr apps with @askrjs/themes, tokens, data-theme, ThemeScope, shell/nav/layout primitives, data-slot selectors, visual quality audits, dark mode, and theme/app boundary decisions.
+---
+
+# Askr Theming
+
+Use this when styling an Askr app with the theme layer. The goal is one obvious shell, one obvious token strategy, and no app-local clones of solved surfaces.
+
+## Inspect First
+
+- `src/styles.css` and `src/styles/*`
+- The root layout or app shell that imports the theme
+- Existing shared components and `@askrjs/themes` imports
+- The nearest screen with the same layout or surface pattern
+
+## Use This When
+
+- You are styling a new product surface.
+- You need dark mode, shell chrome, or token overrides.
+- You want the default Askr admin or SaaS visual language.
+- You are tempted to create local `Card`, `Panel`, `Sidebar`, `Toolbar`, or `EmptyState` components.
+
+## Choose The Layer
+
+- Use `@askrjs/themes` when the existing app already uses the default visual layer.
+- Use `@askrjs/ui` directly only when the app already owns its own visual system and just needs headless behavior.
+- Create an app-local wrapper only when it adds clear product semantics beyond one screen.
+
+## Do This In Order
+
+1. Import the theme once at the app boundary or stylesheet entry.
+2. Reuse existing theme primitives for shells, navigation, layout, surfaces, feedback, and forms.
+3. Override semantic `--ak-*` tokens in CSS, not runtime TypeScript.
+4. Use `data-slot` or documented selectors for local CSS hooks.
+5. Check the result in mobile, desktop, light, dark, empty, error, and disabled states.
+
+## Copy This Shape
+
+```ts
+import "@askrjs/themes/default";
+import {
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Container,
+  EmptyState,
+  Section,
+  Shell,
+  ShellMain,
+  ShellNav,
+  Stack,
+  ThemeScope,
+} from "@askrjs/themes/components";
+```
+
+## Never Do These
+
+- Moving runtime behavior into theme files.
+- Treating theme components as app state containers.
+- Hardcoded non-token colors when tokens exist.
+- Deep internal selectors or `!important`.
+- Marketing-page assumptions in operational SaaS surfaces.
+- Inventing app-local `Panel`, `HStack`, `VStack`, `Page`, `Toolbar`, `Badge`, `Card`, or `EmptyState` components before checking the theme surface.
+- Recreating shell, nav, feedback, form field, or responsive layout primitives already exported by `@askrjs/themes`.
+
+## Validate
+
+- No clipped text, horizontal overflow, or broken shell composition.
+- Focus, hover, disabled, empty, and error states are styled deliberately.
+- Dark mode is intentional, not inverted by accident.
+- App CSS remains override-friendly and token-based.
+
+## Done When
+
+- The surface reuses the existing theme layer instead of inventing a second one.
+- Tokens live in CSS and behavior stays in components.
+- The interface remains coherent across responsive and state changes.
+
+## Handoff
+
+- Use `askr-ui-composition` when the hard part is behavior and composition, not visual styling.
+- Use `askr-accessibility` when announcements, focus, or semantic behavior need review.
+- Use `askr-testing-determinism` before closing visible UI changes.

package/skills/askr-theming/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr Theming"
+  short_description: "Style apps with Askr themes"
+  default_prompt: "Use $askr-theming to apply tokens, shells, navs, and theme rules."