### Install Project Dependencies

Source: https://github.com/astrskai/astrsk/blob/develop/apps/electron/README.md

Run this command to install all necessary project dependencies.

```bash
$ npm install
```

--------------------------------

### Start Development Server

Source: https://github.com/astrskai/astrsk/blob/develop/apps/electron/README.md

Use this command to start the development server and begin working on the application.

```bash
$ npm run dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/CONTRIBUTING.md

Install dependencies for the web application and optionally for the desktop application.

```bash
# Web app dependencies
cd apps/web
npm install

# Desktop app dependencies (optional)
cd ../desktop
npm install
```

--------------------------------

### Start Development Servers

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/CONTRIBUTING.md

Start the development server for the web application and the desktop application in separate terminals.

```bash
# For web app
cd apps/web
npm run dev

# For desktop app (in a separate terminal)
cd apps/desktop
npm run dev
```

--------------------------------

### Install Web App Dependencies

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/README_temp.md

Navigate to the web app directory and install its dependencies using npm.

```bash
cd apps/web
npm install
```

--------------------------------

### Install Desktop App Dependencies

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/README_temp.md

Navigate to the desktop app directory and install its dependencies using npm.

```bash
cd apps/desktop
npm install
```

--------------------------------

### Set Up Local Environment Variables

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/CONTRIBUTING.md

Copy the example environment file to create your local environment configuration.

```bash
# Copy the example environment file
cp .env.example .env.local
```

--------------------------------

### Install Astrsk Design System

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/src/Introduction.mdx

Install the design system package using npm or pnpm.

```bash
npm install @astrsk/design-system
# or
pnpm add @astrsk/design-system
```

--------------------------------

### Start Desktop App Development Mode

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/README_temp.md

Start the desktop application in development mode. It defaults to http://localhost:5173, but can be overridden using the MAIN_VITE_PWA_URL environment variable.

```bash
# Default .env.development already points to http://localhost:5173
# To use a different URL, modify .env.development or set:
export MAIN_VITE_PWA_URL=http://your-dev-url:port
npm run dev
```

--------------------------------

### Development Command: Start PWA Dev Server

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Use this command to start the Progressive Web App development server.

```bash
pnpm dev:pwa
```

--------------------------------

### Clone astrsk.ai Repository

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/README_temp.md

Clone the astrsk.ai repository to get started with the project locally.

```bash
git clone https://github.com/harpychat/astrsk.ai.git
cd astrsk.ai
```

--------------------------------

### Run PWA Development Server

Source: https://github.com/astrskai/astrsk/blob/develop/README.md

Command to start the PWA development server. Displays local and network addresses upon successful startup.

```bash
$ pnpm dev:pwa
... 
pwa:dev:   VITE v6.3.5  ready in 500 ms
pwa:dev: 
pwa:dev:   ➜  Local:   https://localhost:5173/ 
pwa:dev:   ➜  Network: https://172.30.1.34:5173/ 
pwa:dev:   ➜  Network: https://169.254.224.249:5173/ 
pwa:dev:   ➜  press h + enter to show help
```

--------------------------------

### Add Vite Basic SSL Plugin

Source: https://github.com/astrskai/astrsk/blob/develop/README.md

Installs the @vitejs/plugin-basic-ssl development dependency for PWA self-hosting.

```bash
$ pnpm --filter pwa add -D @vitejs/plugin-basic-ssl
```

--------------------------------

### Run Development Mode with Hot Reload

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/GEMINI.md

Use this command to start the development server with hot reloading enabled for rapid iteration.

```bash
npm run dev
```

--------------------------------

### Complete Example: Update Node Position with Optimistic Updates

Source: https://github.com/astrskai/astrsk/blob/develop/TANSTACK_QUERY.md

A comprehensive example demonstrating optimistic updates for changing a node's position within a flow. It includes cancelling queries, snapshotting, optimistic cache updates, error rollback, and final server synchronization.

```typescript
export const useUpdateNodePosition = (flowId: string) => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({ nodeId, position }: { nodeId: string; position: { x: number; y: number } }) => {
      return FlowService.updateNodePosition(flowId, nodeId, position);
    },

    onMutate: async ({ nodeId, position }) => {
      // Cancel ongoing queries
      await queryClient.cancelQueries({ queryKey: flowKeys.nodes(flowId) });

      // Snapshot
      const previousNodes = queryClient.getQueryData(flowKeys.nodes(flowId));

      // Optimistic update
      queryClient.setQueryData(flowKeys.nodes(flowId), (old: Node[]) =>
        old.map(node =>
          node.id === nodeId
            ? { ...node, position }
            : node
        )
      );

      return { previousNodes };
    },

    onError: (err, variables, context) => {
      // Rollback
      if (context?.previousNodes) {
        queryClient.setQueryData(flowKeys.nodes(flowId), context.previousNodes);
      }
      toast.error('Failed to update node position');
    },

    onSettled: () => {
      // Sync with server
      queryClient.invalidateQueries({ queryKey: flowKeys.nodes(flowId) });
    }
  });
};
```

--------------------------------

### TopNavigation Transparency Example

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/docs/sort-dialog-usage.md

Demonstrates how to enable transparency mode on the TopNavigation component using the `transparent` and `transparencyLevel` props. This is useful for overlay scenarios.

```typescript
<TopNavigation
  title="Session Name"
  transparent={true}
  transparencyLevel={50}
  className="z-20"
  leftAction={<BackButton />}
  rightAction={<SettingsButton />}
/>
```

--------------------------------

### Development Commands for Astrsk PWA

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/README.md

Provides commands to start the development server for the Astrsk PWA. Use the monorepo root command or navigate to the PWA directory.

```bash
# From monorepo root
pnpm dev:pwa

# Or from this directory
pnpm dev
```

--------------------------------

### Container/Presenter Pattern Example

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Separate data fetching and business logic (Container) from UI rendering (Presenter) for cleaner, more maintainable components.

```typescript
// Container (data logic)
export const SessionPanelContainer = () => {
  const { data } = useSessionQuery(sessionId);
  return <SessionPanel session={data} />;
};

// Presenter (UI only)
export const SessionPanel = ({ session }) => {
  return <div>{session.name}</div>;
};
```

--------------------------------

### LabeledInput Component Examples

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Demonstrates LabeledInput with various configurations, including different `labelPosition` values ('top', 'left', 'inner'), hints, and error messages.

```tsx
<LabeledInput label="Email" placeholder="Enter email" />
<LabeledInput label="Password" type="password" error="Invalid password" />
<LabeledInput label="Name" hint="Optional" />
<LabeledInput label="Username" labelPosition="left" />
<LabeledInput label="Field" labelPosition="inner" />
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for features, bug fixes, documentation, and breaking changes.

```bash
# Feature
feat(flow-editor): add branching logic for narrative flows

# Bug fix
fix(session): resolve memory leak in session cleanup

# Documentation
docs: update API documentation for v2.0

# With breaking change
feat(agent)!: redesign agent configuration schema

BREAKING CHANGE: Agent config now requires explicit provider selection
```

--------------------------------

### Adaptive Component Pattern Example

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Implement responsive behavior within a single component using hooks like `useBreakpoint`. Avoid creating separate mobile-specific files (`-mobile.tsx`).

```typescript
// GOOD: Single component with responsive behavior
export const SessionPanel = () => {
  const { isMobile } = useBreakpoint();
  return isMobile ? <MobileLayout /> : <DesktopLayout />;
};

// BAD: Separate mobile file (FORBIDDEN)
// session-panel-mobile.tsx
```

--------------------------------

### Feature Flag Usage Example

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Demonstrates how to use the Feature Flag context to check if a feature is enabled. Requires the FeatureFlagContext to be set up.

```typescript
const isEnabled = useFeatureFlag(FEATURE_FLAGS.EXPERIMENTAL_FEATURE_X);
```

--------------------------------

### Write Unit Tests with Vitest

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/CONTRIBUTING.md

Example of writing a unit test for the Agent class using Vitest, asserting the creation of an agent with valid properties.

```typescript
import { describe, it, expect } from 'vitest';
import { Agent } from './agent';

describe('Agent', () => {
  it('should create agent with valid properties', () => {
    const agent = Agent.create({
      name: 'Test Agent',
      prompt: 'You are a helpful assistant',
      providerId: 'openai'
    });
    
    expect(agent.isOk()).toBe(true);
    expect(agent.value.name).toBe('Test Agent');
  });
});
```

--------------------------------

### Measure Initialization Time

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/INITIALIZATION_SYSTEM.md

Measure the total time taken for application initialization by recording the start time and calculating the difference after all initialization tasks are complete.

```typescript
const startTime = performance.now();
// ... initialization ...
const initTime = performance.now() - startTime;
logger.debug(`✅ Initialization completed in ${Math.round(initTime)}ms`);
```

--------------------------------

### Setup DesignSystemProvider with Next.js Image Optimization

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Wrap your application with DesignSystemProvider to enable framework-specific image optimization. This is useful for components like CharacterCard and SessionCard.

```tsx
// app/providers.tsx or _app.tsx
import { DesignSystemProvider } from '@astrsk/design-system';
import Image from 'next/image';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <DesignSystemProvider
      imageComponent={({ src, alt, className, sizes, loading, onError, fill, priority }) => (
        <Image
          src={src}
          alt={alt}
          className={className}
          sizes={sizes}
          loading={loading}
          onError={onError}
          fill={fill}
          priority={priority}
          style={{ objectFit: 'cover' }}
        />
      )} 
    >
      {children}
    </DesignSystemProvider>
  );
}
```

--------------------------------

### Override Theme Variables with CSS

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Demonstrates how to customize the design system's appearance by redefining CSS variables in your global CSS file. Includes examples for backgrounds, foregrounds, borders, inputs, and buttons.

```css
:root {
  /* Backgrounds */
  --bg-canvas: #000000;
  --bg-surface: #0a0a0c;

  /* Foreground */
  --fg-default: #ffffff;
  --fg-muted: #e2e2e8;
  --fg-subtle: #9898a4;

  /* Borders */
  --border-default: #232328;
  --border-focus: #5b82ba;

  /* Input */
  --input-bg: #232328;
  --input-border: #3a3a42;

  /* Button */
  --btn-primary-bg: #4a6fa5;
  --btn-primary-fg: #ffffff;
}
```

--------------------------------

### Build for Production

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/GEMINI.md

Execute this command to create an optimized production build of the application.

```bash
npm run build
```

--------------------------------

### Preview Production Build

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/GEMINI.md

Use this command to preview the production build locally before deployment.

```bash
npm run preview
```

--------------------------------

### Build Application for Windows

Source: https://github.com/astrskai/astrsk/blob/develop/apps/electron/README.md

Execute this command to build the application specifically for the Windows platform.

```bash
# For windows
$ npm run build:win
```

--------------------------------

### Build Application for Linux

Source: https://github.com/astrskai/astrsk/blob/develop/apps/electron/README.md

Execute this command to build the application specifically for the Linux platform.

```bash
# For Linux
$ npm run build:linux
```

--------------------------------

### LabeledTextarea Component Configurations

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Examples of LabeledTextarea with different labels, hints, and error messages, similar to LabeledInput.

```tsx
<LabeledTextarea label="Bio" placeholder="Tell us about yourself..." />
<LabeledTextarea label="Notes" hint="Max 500 characters" required />
<LabeledTextarea label="Description" error="Too short" />
```

--------------------------------

### Textarea Component Usage

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Basic examples of the Textarea component, showing a default placeholder and adjusting the number of rows.

```tsx
<Textarea placeholder="Enter message..." />
<Textarea rows={6} />
```

--------------------------------

### Build Electron Application

Source: https://github.com/astrskai/astrsk/blob/develop/README.md

Command to build the Electron application.

```bash
$ pnpm build:electron
```

--------------------------------

### Update Fork with Upstream Changes

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/CONTRIBUTING.md

Before starting new work, update your local develop branch with the latest changes from the upstream repository.

```bash
git checkout develop
git pull upstream develop
```

--------------------------------

### Testing Command: Run All Tests

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Execute all project tests.

```bash
pnpm test
```

--------------------------------

### Initialize Services with Dependencies

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/INITIALIZATION_SYSTEM.md

Initialize services by respecting their dependency order, ensuring that dependent services are initialized only after their prerequisites are met. Pass necessary dependencies as arguments.

```typescript
// init-services.ts
AssetService.init(); // No dependencies
GeneratedImageService.init(
  // Depends on AssetService
  AssetService.saveFileToAsset,
  AssetService.deleteAsset,
);
CardService.init(
  // Depends on AssetService + GeneratedImageService
  AssetService.assetRepo,
  AssetService.saveFileToAsset,
  AssetService.cloneAsset,
  GeneratedImageService.generatedImageRepo, // ← Dependency
);
```

--------------------------------

### Agent Operations using AgentService

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/src/features/flow/panels/flow-panel-migration-todo.md

Examples of direct calls to AgentService for agent operations. These might remain as direct calls due to their nature.

```javascript
AgentService.cloneAgent.execute()
```

```javascript
AgentService.saveAgent.execute()
```

```javascript
AgentService.deleteAgent.execute()
```

```javascript
AgentService.getAgent.execute()
```

--------------------------------

### Build Application for macOS

Source: https://github.com/astrskai/astrsk/blob/develop/apps/electron/README.md

Execute this command to build the application specifically for the macOS platform.

```bash
# For macOS
$ npm run build:mac
```

--------------------------------

### Build Command: Build PWA

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Build the Progressive Web App, including feature flags.

```bash
pnpm build:pwa
```

--------------------------------

### Project Structure Overview

Source: https://github.com/astrskai/astrsk/blob/develop/README.md

Illustrates the directory layout for the PWA and Electron applications, along with shared packages.

```tree
astrsk/
├── apps/
│   ├── pwa/                  # Main PWA application (Feature-Sliced Design)
│   │   └── src/
│   │       ├── app/          # App initialization, providers, services
│   │       ├── pages/        # Route pages (1 route = 1 page)
│   │       ├── widgets/      # Reusable UI blocks across pages
│   │       ├── features/     # User interactions & business logic
│   │       │   ├── character/
│   │       │   ├── flow/
│   │       │   ├── session/
│   │       │   └── vibe/
│   │       ├── entities/     # Business domain models
│   │       │   ├── agent/
│   │       │   ├── card/
│   │       │   ├── flow/
│   │       │   └── session/
│   │       ├── shared/       # Foundation (UI kit, hooks, utilities)
│   │       ├── db/           # Database schema and migrations
│   │       └── routes/       # TanStack Router route definitions
│   └── electron/             # Electron wrapper (native desktop app)
│       ├── src/
│       │   ├── main/         # Main process (window management, IPC)
│       │   ├── preload/      # Preload scripts (secure bridge)
│   │   └── shared/       # Shared types and constants
│       └── electron-builder.yml
└── packages/
    └── design-system/        # Shared UI components library
```

--------------------------------

### IconInput Component with Search Icon

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Example of using the IconInput component with a Lucide React search icon. Accepts an `icon` prop and all Input props.

```tsx
import { Search } from 'lucide-react';

<IconInput icon={<Search />} placeholder="Search..." />
```

--------------------------------

### Feature Flag Rollback Command

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Provides an example command to roll back a feature flag by setting its corresponding environment variable before building and deploying.

```bash
VITE_FEATURE_X=false pnpm build:pwa && pnpm deploy
```

--------------------------------

### Import and Instantiate Recovery Service (Browser)

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/src/app/recovery-services/README.md

Import the LegacyCharacterRecovery service in the browser console and create an instance. This is the first step for end-users to access recovery functionalities.

```javascript
const { LegacyCharacterRecovery } = await import('/src/app/recovery-services/index.ts');
const recovery = new LegacyCharacterRecovery();
```

--------------------------------

### Tailwind Classes for Typography

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/src/docs/Typography.mdx

Provides examples of using Tailwind CSS classes to apply typography styles for headings, body text, and code elements.

```html
<h1 class="font-display text-2xl font-bold leading-tight">Heading</h1>
<p class="font-sans text-base leading-normal">Body text</p>
<code class="font-mono text-sm">Code snippet</code>
```

--------------------------------

### Development Scripts

Source: https://github.com/astrskai/astrsk/blob/develop/README.md

Common commands for managing project dependencies, running development servers, and building applications.

```bash
# Install dependencies
$ pnpm install

# Run PWA dev server
$ pnpm dev:pwa

# Build PWA application
$ pnpm build:pwa

# Run electron dev application
$ pnpm dev:electron
```

--------------------------------

### Compound Component Pattern Example

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Use this pattern for complex UI components that require flexibility. It allows breaking down a component into smaller, manageable parts.

```typescript
export const SessionPanel = ({ children }) => {
  return <div>{children}</div>;
};

SessionPanel.Header = ({ children }) => <header>{children}</header>;
SessionPanel.Messages = ({ children }) => <main>{children}</main>;
SessionPanel.Input = ({ children }) => <footer>{children}</footer>;
```

--------------------------------

### Enable Light Theme

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/src/Introduction.mdx

Apply the `.light` class to the `<html>` element to switch the theme to light mode.

```html
<html class="light">
  <!-- Light theme -->
</html>
```

--------------------------------

### Import Styles and Components

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/src/Introduction.mdx

Import the global styles once in your application's entry point and then import individual components and utilities as needed.

```tsx
// 1. Import styles once in your app's entry point
import '@astrsk/design-system/styles';

// 2. Import components and utilities
import { cn } from '@astrsk/design-system';
```

--------------------------------

### Download Backup (Browser Console)

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/src/app/recovery-services/README.md

Utilize the downloadBackup method to generate and download a JSON backup of the legacy data. This is an optional safety measure before or after recovery.

```javascript
// Create a downloadable backup file
await recovery.downloadBackup();

// Downloads: astrsk-legacy-backup-1234567890.json
```

--------------------------------

### Design System Provider and Component Usage

Source: https://context7.com/astrskai/astrsk/llms.txt

Wrap your application with DesignSystemProvider to configure asset URLs and event handlers. Examples show CharacterCard, SessionCard, and TabBar usage.

```tsx
import {
  Button,
  Input, IconInput, PasswordInput, SearchInput,
  LabeledInput, LabeledTextarea,
  Select,
  Accordion,
  Avatar,
  Label,
  Skeleton,
  TabBar,
  Textarea,
  CharacterCard, CharacterCardSkeleton,
  SessionCard, SessionCardSkeleton,
} from "@astrsk/design-system";
import { DesignSystemProvider } from "@astrsk/design-system/provider";

// Wrap app with the provider
function App({ children }: { children: React.ReactNode }) {
  return (
    <DesignSystemProvider
      getImageUrl={(assetId) => `/assets/${assetId}`}
      onLikeCard={(cardId) => handleLike(cardId)}
    >
      {children}
    </DesignSystemProvider>
  );
}

// Character card display
<CharacterCard
  title="Aria"
  iconUrl="/assets/aria-icon.png"
  tags={["fantasy", "mage"]}
  creator="user123"
  isLiked={false}
  likeCount={42}
  usageCount={150}
  onLike={() => toggleLike("card-uuid")}
  onClick={() => navigateTo("/cards/card-uuid")}
/>

// Session card display
<SessionCard
  title="The Ancient Tower"
  coverUrl="/assets/session-cover.jpg"
  characters={[
    { name: "Aria", iconUrl: "/assets/aria.png" },
    { name: "Alex", iconUrl: undefined },
  ]}
  updatedAt={new Date()}
  onClick={() => openSession("session-uuid")}
/>

// Loading states
<CharacterCardSkeleton />
<SessionCardSkeleton />

// Tab bar navigation
<TabBar
  tabs={[
    { id: "characters", label: "Characters" },
    { id: "flows", label: "Flows" },
    { id: "sessions", label: "Sessions" },
  ]}
  activeTab="characters"
  onChange={(tabId) => navigate(tabId)}
/>

// Icon-prefixed input
<IconInput
  icon={<SearchIcon />}
  placeholder="Search characters..."
  value={query}
  onChange={(e) => setQuery(e.target.value)}
/>
```

--------------------------------

### Testing Command: Run Tests with Coverage

Source: https://github.com/astrskai/astrsk/blob/develop/CLAUDE.md

Run all tests and generate a coverage report. Ensure coverage is at least 80%.

```bash
pnpm test --coverage
```

--------------------------------

### Override Theme Variables

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/src/Introduction.mdx

Customize the design system's appearance by redefining CSS variables in your global CSS. This example shows how to change input and button styles.

```css
/* Your app's global CSS */
:root {
  /* Change input styles */
  --input-bg: #1e1e2e;
  --input-border: #45475a;

  /* Change button colors */
  --btn-primary-bg: #89b4fa;
  --btn-primary-fg: #1e1e2e;

  /* Change semantic colors */
  --bg-surface: #181825;
  --fg-default: #cdd6f4;
}
```

--------------------------------

### Lint the Codebase

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/GEMINI.md

Run this command to check the codebase for style and potential errors using ESLint.

```bash
npm run lint
```

--------------------------------

### Use Components with Subpath Imports (Recommended)

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Import only the specific components you need from their respective subpaths for better tree-shaking and smaller bundle sizes.

```tsx
import { Button } from '@astrsk/design-system/button';
import { Input } from '@astrsk/design-system/input';
import { LabeledInput } from '@astrsk/design-system/labeled-input';

function App() {
  return (
    <div>
      <Button variant="default">Click me</Button>
      <Input placeholder="Basic input" />
      <LabeledInput label="Email" type="email" />
    </div>
  );
}
```

--------------------------------

### SortDialog with Specific Enum Values

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/docs/sort-dialog-usage.md

An example of using SortDialog with specific enum values for sort options, such as `SearchCardsSort`. Ensure the `onSort` callback correctly types the received value.

```typescript
import { SearchCardsSort } from "@/modules/card/repos";
import { SortDialog } from "@/components-v2/sort-dialog";

const sortOptions = [
  { value: SearchCardsSort.Latest, label: "Newest First" },
  { value: SearchCardsSort.Oldest, label: "Oldest First" },
  { value: SearchCardsSort.TitleAtoZ, label: "Title (A-Z)" },
  { value: SearchCardsSort.TitleZtoA, label: "Title (Z-A)" },
];

<SortDialog
  options={sortOptions}
  onSort={(value) => handleSortChange(value as SearchCardsSort)}
/>
```

--------------------------------

### Get Next Available Color Helper Function

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/src/features/flow/panels/flow-panel-migration-todo.md

A helper function to determine the next available color for nodes in a flow. It requires access to flow agents and node properties.

```javascript
getNextAvailableColor(flow)
```

--------------------------------

### Run Quality Checks

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/CONTRIBUTING.md

Execute linting, testing, and build commands to ensure code quality and check for errors before committing.

```bash
# Lint your code
npm run lint

# Run tests
npm run test
npm run test:e2e

# Build to check for errors
npm run build
```

--------------------------------

### Standard Mutation with Optimistic Updates

Source: https://github.com/astrskai/astrsk/blob/develop/TANSTACK_QUERY.md

Implement optimistic updates for mutations to provide instant UI feedback. This example shows how to update the cache before the mutation resolves and roll back on error.

```typescript
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { flowKeys } from './query-factory';
import { FlowService } from '@/app/services/flow-service';

export const useUpdateFlowTitle = (flowId: string) => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (title: string) => {
      return FlowService.updateTitle(flowId, title);
    },

    onMutate: async (title) => {
      // 1. Cancel outgoing queries (prevent race conditions)
      await queryClient.cancelQueries({ queryKey: flowKeys.detail(flowId) });

      // 2. Snapshot previous value for rollback
      const previous = queryClient.getQueryData(flowKeys.detail(flowId));

      // 3. Optimistically update cache
      queryClient.setQueryData(flowKeys.detail(flowId), (old: Flow) => ({
        ...old,
        title,
      }));

      // 4. Return context for error handler
      return { previous };
    },

    onError: (err, variables, context) => {
      // Rollback to previous value on error
      if (context?.previous) {
        queryClient.setQueryData(flowKeys.detail(flowId), context.previous);
      }
    },

    onSettled: async () => {
      // Refetch to ensure sync with server
      await queryClient.invalidateQueries({ queryKey: flowKeys.detail(flowId) });
    }
  });
};
```

--------------------------------

### Character Cards Table Schema

Source: https://context7.com/astrskai/astrsk/llms.txt

Extends the base 'cards' table with specific fields for character cards, including name, description, example dialogue, and lorebook entries. Used for defining AI personas.

```sql
CREATE TABLE character_cards (
  id                uuid PRIMARY KEY,              -- FK → cards.id
  name              varchar NOT NULL,
  description       text,
  example_dialogue  text,
  lorebook          jsonb,                         -- { entries: LorebookEntry[] }
  created_at        timestamp DEFAULT now(),
  updated_at        timestamp DEFAULT now()
);
```

--------------------------------

### App Initialization Flow

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/INITIALIZATION_SYSTEM.md

Orchestrates the sequential initialization process including database migration checks, service initialization, and store population. Logs are saved only on the first initialization.

```typescript
async function initializeApp() {
  // Check if database is already migrated
  const dbInitialized = await isDatabaseInitialized();

  if (!dbInitialized) {
    // First-time initialization: Run full migration
    await migrate(onProgress);
  } else {
    // Subsequent loads: Skip migration, mark as instant success
    markMigrationStepsAsSuccess();
  }

  // ALWAYS run services (dependency injection)
  await initServices(onProgress);

  // ALWAYS run stores (data loading)
  await initStores(onProgress);

  // Save log only on first initialization
  if (!dbInitialized) {
    saveLog(initTime);
  }
}
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/README_temp.md

Execute all unit tests in the project. This command is useful for verifying the integrity of individual code components.

```bash
npm run test
```

--------------------------------

### Renderer Process IPC Communication

Source: https://context7.com/astrskai/astrsk/llms.txt

In the renderer process, use the preload bridge to invoke or listen for IPC events. This example demonstrates auto-updates, window management, data persistence, HTTP proxying for CORS bypass, and configuration settings.

```typescript
import {
  UPDATER_CHANNEL,
  TOP_BAR_CHANNEL,
  DUMP_CHANNEL,
  HTTP_PROXY_CHANNEL,
  CONFIG_CHANNEL,
} from "../shared/ipc-channels";

// Check for and install auto-updates
window.electron.ipcRenderer.invoke(UPDATER_CHANNEL.CHECK_FOR_UPDATES);
window.electron.ipcRenderer.on(UPDATER_CHANNEL.ON_UPDATE_AVAILABLE, (_, info) => {
  console.log("Update available:", info.version);
  window.electron.ipcRenderer.invoke(UPDATER_CHANNEL.DOWNLOAD_UPDATE);
});
window.electron.ipcRenderer.on(UPDATER_CHANNEL.ON_UPDATE_DOWNLOADED, () => {
  window.electron.ipcRenderer.invoke(UPDATER_CHANNEL.QUIT_AND_INSTALL);
});

// Window management
window.electron.ipcRenderer.invoke(TOP_BAR_CHANNEL.WINDOW_MAXIMIZE);
window.electron.ipcRenderer.invoke(TOP_BAR_CHANNEL.WINDOW_MINIMIZE);
window.electron.ipcRenderer.invoke(TOP_BAR_CHANNEL.NEW_WINDOW);

// Persist arbitrary data via electron-store (bypasses browser storage limits)
window.electron.ipcRenderer.invoke(DUMP_CHANNEL.SET_DUMP, "snapshot-key", largeDataJson);
const data = await window.electron.ipcRenderer.invoke(DUMP_CHANNEL.GET_DUMP, "snapshot-key");

// Stream HTTP request through main process (bypasses CORS)
const reqId = crypto.randomUUID();
window.electron.ipcRenderer.invoke(HTTP_PROXY_CHANNEL.STREAM_START, reqId, {
  url: "https://api.openai.com/v1/chat/completions",
  method: "POST",
  headers: { Authorization: "Bearer sk-..." },
  body: JSON.stringify({ model: "gpt-4o", messages: [...], stream: true }),
});
window.electron.ipcRenderer.on(HTTP_PROXY_CHANNEL.STREAM_CHUNK, (_, id, chunk) => {
  if (id === reqId) process(chunk);
});
window.electron.ipcRenderer.on(HTTP_PROXY_CHANNEL.STREAM_END, (_, id) => {
  if (id === reqId) console.log("Stream complete");
});

// Electron-level config (e.g. allow mixed content for local LLM servers)
await window.electron.ipcRenderer.invoke(CONFIG_CHANNEL.SET_CONFIG, "allowInsecureContent", true);
```

--------------------------------

### Start Vibe Coding Request and Session Monitoring

Source: https://context7.com/astrskai/astrsk/llms.txt

Defines the structure for initiating an AI-driven editing session and monitoring its progress. Ensure all necessary types are imported from 'vibe-shared-types'. The session status can be checked using helper functions like isActiveStatus and isCompletedStatus.

```typescript
import {
  type StartVibeCodingRequest,
  type VibeCodingSessionStatus,
  type EditableFlowData,
  type EditableCharacterCard,
  type StructuredChange,
  SESSION_STATUS,
  isActiveStatus,
  isCompletedStatus,
  transformToCreateEditingSessionArgs,
} from "vibe-shared-types";

// Start a vibe coding request
const request: StartVibeCodingRequest = {
  originalRequest: "Make Aria more mysterious and add a dark backstory",
  context: {
    resourceId: "card-uuid",
    resourceType: "character_card",
    resourceName: "Aria",
    availableResources: [
      {
        id: "card-uuid",
        type: "character_card",
        name: "Aria",
        data: {
          common: { title: "Aria" },
          character: {
            name: "Aria",
            description: "An elf mage.",
            example_dialogue: "",
            lorebook: { entries: [] },
          },
        } satisfies EditableCharacterCard,
      },
    ],
  },
  modelId: "openai-compatible:google/gemini-2.5-flash",
};

// Transform to Convex backend format
const sessionId = crypto.randomUUID();
const convexArgs = transformToCreateEditingSessionArgs(request, sessionId);

// Monitor session status
const session: VibeCodingSessionStatus = await pollSession(sessionId);

if (session.status === SESSION_STATUS.COMPLETED) {
  console.log("Changes applied:", session.results?.totalEdits);
} else if (isActiveStatus(session.status)) {
  console.log("Still processing:", session.currentStep);
}
```

--------------------------------

### Astrsk PWA Scripts Overview

Source: https://github.com/astrskai/astrsk/blob/develop/apps/pwa/README.md

Lists available npm scripts for managing the Astrsk PWA, including development, building, previewing, testing, linting, and database operations.

```bash
| Command | Description |
|---------|-------------|
| `pnpm dev` | Start development server (port 5173) |
| `pnpm build` | Build for production |
| `pnpm preview` | Preview production build |
| `pnpm test` | Run tests with Vitest |
| `pnpm lint` | Run ESLint |
| `pnpm db:export` | Export database to JSON |
```

--------------------------------

### Design System Development Commands

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Essential commands for managing dependencies, running Storybook, building the library, and type checking.

```bash
# Install dependencies
pnpm install

# Run Storybook
pnpm dev

# Build library
pnpm build

# Build Storybook
pnpm build-storybook

# Type check
pnpm lint
```

--------------------------------

### Select Component Options and States

Source: https://github.com/astrskai/astrsk/blob/develop/packages/design-system/README.md

Shows how to configure the Select component with options, placeholders, default values, and disabled or invalid states.

```tsx
const options = [
  { value: 'option1', label: 'Option 1' },
  { value: 'option2', label: 'Option 2' },
  { value: 'option3', label: 'Option 3', disabled: true },
];

<Select options={options} placeholder="Select an option..." />
<Select options={options} defaultValue="option1" />
<Select options={options} disabled />
<Select options={options} aria-invalid="true" />
```