### Quick Start Development Setup

Source: https://github.com/coollabsio/jean/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies using bun, and start the development server.

```bash
# Clone the repository
git clone https://github.com/coollabsio/jean.git
cd jean

# Install dependencies
bun install

# Start development
bun run tauri:dev # Also keeps the web-access dist rebuilt in the background
```

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

### Install Dependencies and Start Development Server

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Commands to clone the repository, install dependencies using Bun, and start the development server.

```bash
git clone https://github.com/your-username/tauri-template.git
cd tauri-template

bun install

bun run dev
```

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

### Install Project Dependencies

Source: https://github.com/coollabsio/jean/blob/main/docs/GETTING_STARTED.md

Install all necessary project dependencies using Bun.

```bash
bun install
```

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

### Install Jean with Homebrew

Source: https://github.com/coollabsio/jean/blob/main/README.md

Use Homebrew to tap the Jean repository and install the cask.

```bash
brew tap coollabsio/jean
brew install --cask jean
```

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

### Start Development Server

Source: https://github.com/coollabsio/jean/blob/main/docs/GETTING_STARTED.md

Start the development server for the React application or the full Tauri app with a watcher.

```bash
bun run dev        # React dev server only
bun run tauri:dev  # Full Tauri app + web-access dist watcher
```

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

### Update Complete Dialog Message

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/auto-updates.md

Example message shown to the user after an update has been successfully downloaded and is ready to be installed.

```text
Update completed successfully!

The application needs to restart to apply the update.
Would you like to restart now?
```

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

### Install Tauri CLI

Source: https://github.com/coollabsio/jean/blob/main/docs/SECURITY_PRODUCTION.md

Install the Tauri CLI globally using Bun. This is a prerequisite for generating signing keys.

```bash
bun add -g @tauri-apps/cli
```

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

### Clone and Navigate Template Repository

Source: https://github.com/coollabsio/jean/blob/main/docs/GETTING_STARTED.md

Clone the template repository and navigate into the project directory to begin setup.

```bash
git clone <your-repo-url>
cd tauri-template
```

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

### Install Linux Dependencies (Arch Linux)

Source: https://github.com/coollabsio/jean/blob/main/CONTRIBUTING.md

Installs webkit2gtk, librsvg, patchelf, and libayatana-appindicator for Arch Linux/Manjaro.

```bash
sudo pacman -S webkit2gtk-4.1 librsvg patchelf libayatana-appindicator
```

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

### Run Development Server with RDP Support

Source: https://github.com/coollabsio/jean/blob/main/CONTRIBUTING.md

Starts the development server, automatically detecting and enabling configurations for RDP/remote desktop sessions.

```bash
# Auto-detects RDP session and enables software rendering
bun run tauri:dev:rdp

# Force software rendering (useful if auto-detection doesn't work)
bun run tauri:dev:rdp -- --force
```

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

### Install macOS Xcode Command Line Tools

Source: https://github.com/coollabsio/jean/blob/main/CONTRIBUTING.md

Run this command to install the necessary Xcode Command Line Tools on macOS.

```bash
xcode-select --install
```

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

### Install Linux Dependencies (Debian/Ubuntu)

Source: https://github.com/coollabsio/jean/blob/main/CONTRIBUTING.md

Installs webkit2gtk, librsvg, patchelf, and optionally libayatana-appindicator for Debian/Ubuntu-based systems.

```bash
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev librsvg2-dev patchelf

# Ubuntu/Linux Mint: prefer Ayatana AppIndicator (avoids conflicts between old libappindicator3 and Ayatana packages)
sudo apt install libayatana-appindicator3-dev

# Debian/older distros (if Ayatana packages are unavailable):
# sudo apt install libappindicator3-dev
```

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

### Install and Use Vite Bundle Analyzer

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/bundle-optimization.md

Install `vite-bundle-analyzer` as a dev dependency and use it to analyze your application's bundle size.

```bash
bun add --dev vite-bundle-analyzer
```

```bash
bunx vite-bundle-analyzer dist/assets/index-*.js
```

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

### Rust Logging Examples

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/logging.md

Demonstrates basic logging calls in Rust using the `log` crate. Ensure the `log` crate is added as a dependency.

```rust
log::info!("Application starting up");
log::debug!("Debug info: {}", some_value);
log::warn!("Something unexpected happened");
log::error!("Error occurred: {}", error);
```

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

### Install sccache

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/build-performance.md

Instructions for installing sccache, a compiler cache, on macOS using Homebrew and on Linux via Cargo or distribution packages.

```bash
# macOS
brew install sccache
```

```bash
# Linux
cargo install sccache --locked
# or use your distro package
```

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

### Direct Store Access for Performance

Source: https://github.com/coollabsio/jean/blob/main/src/lib/commands/README.md

Example of using the `getState()` pattern for direct store access within command execution for optimal performance.

```typescript
execute: context => {
  // ✅ Good: Direct store access in commands
  const { sidebarVisible, toggleSidebar } = useUIStore.getState()
  if (!sidebarVisible) {
    toggleSidebar()
  }
}
```

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

### Define a New Project Command

Source: https://github.com/coollabsio/jean/blob/main/docs/GETTING_STARTED.md

Example of defining a new command for creating a project, including its ID, label, description, group, shortcut, and execution logic.

```typescript
// src/lib/commands/project-commands.ts
export const projectCommands = [
  {
    id: 'new-project',
    label: 'New Project',
    description: 'Create a new project',
    group: 'project',
    shortcut: '⌘+N',
    execute: async context => {
      // Your logic here
      context.showToast('New project created!', 'success')
    },
  },
]
```

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

### Start Jean Headless Server

Source: https://context7.com/coollabsio/jean/llms.txt

Starts the Jean server in headless mode, useful for remote access. You can specify the host and port to bind to. Ensure all Tauri commands are registered in `dispatch.rs` for web transport.

```bash
# Start headless server (no desktop window)
jean --headless --host 127.0.0.1 --port 3456

# Bind to specific network interface (e.g. Tailscale IP)
jean --headless --host 100.64.0.1 --port 3456
```

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

### Rust Integration Test for Tauri Commands

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/testing.md

An example of an integration test for Tauri commands using `mock_app` and `mock_context`. This test requires further setup specific to the commands being tested.

```rust
// src-tauri/tests/integration_test.rs
use tauri::test::{mock_app, mock_context};

#[tokio::test]
async fn test_app_commands() {
    let app = mock_app();
    let context = mock_context();

    // Test Tauri commands in isolation
    // This requires more setup depending on your commands
}

```

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

### Jean Configuration (`jean.json`)

Source: https://context7.com/coollabsio/jean/llms.txt

Manage project lifecycle scripts and port configurations using the `jean.json` file. Read the configuration or manually execute setup scripts.

```APIDOC
## Read Jean Config

### Description
Reads the `jean.json` configuration file for a specific worktree, which includes lifecycle scripts and port definitions.

### Method
`invoke`

### Endpoint
`get_jean_config`

### Parameters
#### Request Body
- **worktreeId** (string) - Required - The ID of the worktree to read the configuration from.

### Response
#### Success Response (200)
- **config** (JeanConfig | null) - The configuration object if found, otherwise null.

### Request Example
```typescript
const config = await invoke<JeanConfig | null>('get_jean_config', {
  worktreeId: 'wt-uuid',
})
// Access scripts and ports via config.scripts and config.ports
```
```

```APIDOC
## Run Setup Script

### Description
Manually executes the setup script defined in the `jean.json` configuration for a given worktree. This operation emits `setup-script-output` events with the script execution results.

### Method
`invoke`

### Endpoint
`run_setup_script`

### Parameters
#### Request Body
- **worktreeId** (string) - Required - The ID of the worktree for which to run the setup script.

### Request Example
```typescript
await invoke('run_setup_script', { worktreeId: 'wt-uuid' })
// Listen for 'setup-script-output' events for results.
```
```

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

### Rust Tauri Command Example (Good vs. Avoid)

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Demonstrates idiomatic Rust for Tauri commands, emphasizing error handling with `Result` and clear naming, compared to less robust approaches.

```rust
// ✅ Good
#[tauri::command]
async fn save_user_data(app: AppHandle, data: UserData) -> Result<(), String> {
    validate_user_data(&data)?;

    let file_path = get_safe_user_data_path(&app)?;
    write_data_atomically(&file_path, &data)
        .map_err(|e| format!("Failed to save user data: {e}"))
}

// ❌ Avoid
#[tauri::command]
fn save(app: AppHandle, d: Value) -> Result<(), String> {
    let p = app.path().app_data_dir().unwrap().join("data.json");
    std::fs::write(p, serde_json::to_string(&d).unwrap()).unwrap();
    Ok(())
}
```

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

### Run Bundle Analysis Script

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/bundle-optimization.md

Execute the template's analysis script to build the application and get insights into bundle size.

```bash
bun run build:analyze
```

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

### Install Playwright for E2E Testing

Source: https://github.com/coollabsio/jean/blob/main/docs/tasks-todo/task-x-e2e-testing-setup.md

Installs Playwright as a development dependency and downloads the Chromium browser. Use this for frontend testing with mocked IPC.

```bash
bun add --dev @playwright/test
npx playwright install chromium
```

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

### Install WebdriverIO and Tauri Driver

Source: https://github.com/coollabsio/jean/blob/main/docs/tasks-todo/task-x-e2e-testing-setup.md

Installs the Tauri driver for Rust backend interaction and WebdriverIO CLI with Mocha framework for E2E testing. This option is for Linux/Windows only.

```bash
cargo install tauri-driver --locked
bun add --dev @wdio/cli @wdio/local-runner @wdio/mocha-framework
```

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

### Multi-Source Event Coordination Example

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/architecture-guide.md

Illustrates how different user interactions (keyboard shortcut, menu item, command palette) can all trigger the same underlying command or function.

```typescript
// All trigger the same command
handleKeyboard('cmd+comma') → commandContext.openPreferences()
handleMenu('menu-preferences') → commandContext.openPreferences()
handleCommand('open-preferences') → commandContext.openPreferences()
```

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

### TypeScript Component Example (Good vs. Avoid)

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Illustrates preferred functional component patterns with hooks and proper typing versus less maintainable alternatives.

```typescript
// ✅ Good
const UserProfile = ({ userId }: { userId: string }) => {
  const { data: user, isLoading } = useUser(userId)

  if (isLoading) return <LoadingSpinner />
  return <div>{user?.name}</div>
}

// ❌ Avoid
const UP = (props: any) => {
  const d = useUser(props.id)
  return d.loading ? <div>Loading...</div> : <div>{d.data.name}</div>
}
```

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

### Frontend Component Test Example

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Example of a basic component test using `@testing-library/react` to verify the rendering of a component in its loading state.

```typescript
// Component tests
import { render, screen } from '@testing-library/react'
import { UserProfile } from './UserProfile'

test('renders user profile with loading state', () => {
  render(<UserProfile userId="123" />)
  expect(screen.getByText('Loading...')).toBeInTheDocument()
})
```

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

### Write a Simple React Unit Test

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/testing.md

Example of a basic unit test for a React component using @testing-library/react.

```typescript
// src/components/ui/Button.test.tsx
import { render, screen } from '@testing-library/react'
import { Button } from './Button'

test('renders button with text', () => {
  render(<Button>Click me</Button>)
  expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument()
})
```

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

### Conventional Commits Examples

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Examples of commit messages formatted according to the Conventional Commits specification, including type, optional scope, and description.

```bash
# Format: <type>[optional scope]: <description>

# Examples:
git commit -m "feat: add user authentication system"
git commit -m "fix(ui): resolve sidebar toggle issue"
git commit -m "docs: update installation instructions"
git commit -m "refactor(store): simplify user state management"
git commit -m "test: add unit tests for preferences service"
```

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

### Configure Project Automation with jean.json

Source: https://context7.com/coollabsio/jean/llms.txt

The `jean.json` file in a project root configures lifecycle scripts (setup/teardown/run) and port labels. Use `get_jean_config` to read the configuration for a worktree and `run_setup_script` to execute the setup script manually.

```json
{
  "scripts": {
    "setup": "npm install && cp .env.example .env",
    "teardown": "docker compose down",
    "run": "npm run dev"
  },
  "ports": [
    { "port": 3000, "label": "Web UI" },
    { "port": 8080, "label": "API" }
  ]
}
```

```typescript
// Read jean.json config for a worktree
const config = await invoke<JeanConfig | null>('get_jean_config', {
  worktreeId: 'wt-uuid',
})
// config.scripts.setup, config.scripts.run, config.ports

// Execute setup script manually
await invoke('run_setup_script', { worktreeId: 'wt-uuid' })
// Emits 'setup-script-output' events with SetupScriptResult
```

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

### Test Jean Setup and Clear Environment

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/troubleshooting.md

Use this command to clear environment variables and restart Jean for testing. It helps in verifying if automatic fixes are working by resetting any manual overrides.

```bash
# Clear environment and restart Jean
unset WEBKIT_DISABLE_COMPOSITING_MODE
unset WEBKIT_DISABLE_DMABUF_RENDERER
unset GDK_BACKEND
./jean
```

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

### Example UI Action Executor Mappings

Source: https://github.com/coollabsio/jean/blob/main/docs/tasks-todo/task-x-voice-actions-command-box.md

Illustrates how specific UI actions map to existing store operations or UI state changes. Avoids duplicating logic within the command box component.

```typescript
switch_project -> useChatStore.getState().clearActiveWorktree()
               -> useProjectsStore.getState().selectProject(projectId)

open_project_settings -> useProjectsStore.getState().openProjectSettings(projectId)

open_archive -> useUIStore.getState().setArchivedModalOpen(true)
```

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

### TypeScript Logging Examples

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/logging.md

Shows how to use the logger utility in TypeScript. Import the logger from '@/lib/logger' and use its methods for different log levels.

```typescript
import { logger } from '@/lib/logger'

logger.info('User action completed')
logger.debug('Debug data', { userId: 123, action: 'click' })
logger.warn('Performance warning')
logger.error('Request failed', { error: response.error })
```

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

### Backend Unit Test Example

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Example of a Rust unit test for validating user data, asserting success for valid data and failure for invalid data.

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_validate_user_data() {
        let valid_data = UserData { name: "John".to_string() };
        assert!(validate_user_data(&valid_data).is_ok());

        let invalid_data = UserData { name: "".to_string() };
        assert!(validate_user_data(&invalid_data).is_err());
    }
}
```

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

### Run All E2E Tests

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/testing.md

Execute all End-to-End tests. The dev server starts automatically on port 1421.

```bash
bun run test:e2e              # Run all E2E tests
bun run test:e2e -- --ui      # Open Playwright UI mode
bun run test:e2e -- tests/chat-messaging.spec.ts  # Run specific file
```

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

### Basic Zustand Store Setup

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/state-management.md

Defines a basic UI state store using Zustand with devtools middleware for debugging. Includes a boolean state and a function to toggle it.

```typescript
import { create } from 'zustand'
import { devtools } from 'zustand/middleware'

interface UIState {
  sidebarVisible: boolean
  toggleSidebar: () => void
}

export const useUIStore = create<UIState>()(
  devtools(
    set => ({
      sidebarVisible: true,
      toggleSidebar: () =>
        set(state => ({ sidebarVisible: !state.sidebarVisible })),
    }),
    { name: 'ui-store' }
  )
)
```

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

### Testing Pattern: Component Testing Setup

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/architectural-patterns.md

Set up a wrapper component for testing React components that utilize TanStack Query. This ensures the query client is available during tests.

```typescript
function TestWrapper({ children }: { children: ReactNode }) {
  return (
    <QueryClientProvider client={testQueryClient}>
      {children}
    </QueryClientProvider>
  )
}
```

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

### Check for Duplicate Dependencies with Bun

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/bundle-optimization.md

Use Bun's package manager to list installed packages and check for version conflicts. Reinstall dependencies if necessary to resolve duplication issues.

```bash
bun pm ls react
# Note: bun doesn't have a dedupe command, reinstall dependencies if needed
bun install
```

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

### Get WebKitGTK Version

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/troubleshooting.md

Check the installed WebKitGTK version to identify known problematic versions. Versions 2.40.x to 2.42.x are noted as potentially causing issues.

```bash
webkit2gtk --version
```

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

### Set up Debugging Re-renders with WDYR

Source: https://github.com/coollabsio/jean/blob/main/CLAUDE.md

To diagnose unnecessary re-renders in React components, install and configure `why-did-you-render`. This tool helps identify components that re-render due to hook changes or equal-by-value object differences. Remember to remove WDYR setup before releasing the application.

```bash
bun add -d @welldone-software/why-did-you-render
```

```typescript
if (import.meta.env.DEV) {
  const whyDidYouRender = (
    await import('@welldone-software/why-did-you-render')
  ).default
  whyDidYouRender(React, { trackAllPureComponents: false })
}
```

```typescript
import './wdyr'
```

```typescript
MyComponent.whyDidYouRender = true
```

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

### Manual Release Steps

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/releases.md

Alternative manual steps for releasing an application. This involves updating versions, running checks, and manually committing and tagging the release.

```bash
# 1. Update versions manually in:
#    - package.json
#    - src-tauri/Cargo.toml
#    - src-tauri/tauri.conf.json

# 2. Run checks
bun run check:all

# 3. Commit and tag
git add .
git commit -m "chore: release v1.0.0"
git tag v1.0.0
git push origin main --tags
```

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

### Configure sccache rustc-wrapper

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/build-performance.md

Set up sccache by configuring the `rustc-wrapper` in a local `.cargo/config.toml` file. The path to the sccache binary is machine-specific and should be found using `which sccache`.

```toml
[build]
rustc-wrapper = "/opt/homebrew/bin/sccache"   # macOS Apple Silicon
# rustc-wrapper = "/usr/local/bin/sccache"    # macOS Intel / older Linux
# rustc-wrapper = "/home/<you>/.cargo/bin/sccache"  # Linux cargo-installed
```

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

### Initialize Claude Code Project

Source: https://github.com/coollabsio/jean/blob/main/docs/GETTING_STARTED.md

Use the /init command in Claude Code to automatically configure the template for your application, including app name, description, identifiers, and workflows.

```bash
/init
```

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

### Version Management and Release Process (Bash)

Source: https://context7.com/coollabsio/jean/llms.txt

Commands for managing project versions and release process using bun and node scripts. Includes version bumping, full release preparation, quality checks, and platform-specific builds.

```bash
# Bump version across package.json, Cargo.toml, and tauri.conf.json
bun run version:bump              # interactive bump
node scripts/bump-version.js 0.2.0
```

```bash
# Full release preparation (runs checks, updates versions, commits & tags)
bun run release:prepare v0.2.0
```

```bash
# Quality gate — run before every release
bun run check:all
# Runs: typecheck, eslint, prettier, cargo fmt, cargo clippy, vitest, cargo test
```

```bash
# Platform-specific builds
bun run tauri:build:macos         # universal binary (arm64 + x86_64)
bun run tauri:build:linux         # .deb + .rpm
bun run tauri:build:linux:appimage
bun run tauri:build:windows       # .msi + NSIS installer
```

```bash
# Development
bun run tauri:dev                 # Tauri + Vite dev server with hot reload
bun run dev:web                   # Vite build --watch (for HTTP server dev)
bun run test:e2e                  # Playwright end-to-end tests
```

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

### JSDoc for Input Sanitization Function

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Add JSDoc comments for complex functions, documenting public APIs thoroughly and including usage examples. This example shows validation and sanitization of user input.

```typescript
/**
 * Validates user input and returns sanitized data
 * @param input - Raw user input string
 * @param maxLength - Maximum allowed length
 * @returns Sanitized string safe for use
 * @example
 * const safe = sanitizeInput("<script>alert('hi')</script>", 100)
 * // Returns: "alert('hi')"
 */
export function sanitizeInput(input: string, maxLength: number): string {
  return input.replace(/[<>]/g, '').slice(0, maxLength).trim()
}
```

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

### Run Jean in Headless Mode

Source: https://github.com/coollabsio/jean/blob/main/README.md

Launch Jean without the desktop window and expose the web UI over HTTP. Specify the host and port for the web server.

```bash
jean --headless --host 127.0.0.1 --port 3456
```

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

### Update Available Dialog Message

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/auto-updates.md

Example message shown to the user when a new update is detected.

```text
Update available: 1.0.1

Current version: 1.0.0
Would you like to download and install this update?
```

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

### No Updates Dialog Message

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/auto-updates.md

Example message displayed when a manual update check finds no new versions available.

```text
You are running the latest version
```

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

### Prepare Release Script

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/releases.md

Execute this command to initiate the release preparation process. It checks git status, runs quality checks, updates version files, and prompts for commit and push.

```bash
bun run release:prepare v1.0.0
```

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

### Get GitHub PR Diff

Source: https://context7.com/coollabsio/jean/llms.txt

Retrieves the diff content for a specific GitHub Pull Request. Requires `projectId` and `prNumber`.

```typescript
// Get PR diff for context
const diff = await invoke<string>('get_pr_diff', {
  projectId: 'proj-uuid',
  prNumber: 101,
})
```

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

### Tauri HTTP Server Commands

Source: https://github.com/coollabsio/jean/blob/main/docs/tasks-todo/task-x-http-server-web-access.md

Defines Tauri commands for managing the HTTP server, including starting, stopping, and retrieving its status.

```rust
// start_http_server(port) → { url, token }
// stop_http_server()
// get_http_server_status() → { running, url?, token?, port? }
```

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

### Push Tags to Origin

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/releases.md

Ensure tags are pushed to the remote repository to trigger release workflows. Tags must start with 'v'.

```bash
git push origin --tags
```

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

### Define Dynamic Invoke Handlers

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/testing.md

Example of dynamic, stateful Tauri command handlers within the browser context for E2E tests.

```typescript
// Inside addInitScript — runs in browser context
if (cmd === 'create_session') {
  const newSession = { id: `session-${Date.now()}`, name: 'New Session', ... }
  store.sessions.push(newSession)
  store.active_session_id = newSession.id
  return newSession
}
```

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

### Manual AppImage Build with NO_STRIP

Source: https://github.com/coollabsio/jean/blob/main/docs/APPMIMAGE_BUILD_ARCH_LINUX.md

This two-step process involves first building the AppDir and then manually running linuxdeploy with the NO_STRIP=1 environment variable to bypass the stripping of ELF sections that cause the build to fail on Arch Linux.

```bash
# Build AppDir first
bun run tauri build --bundles appimage 2>&1 | head -100

# Then manually run linuxdeploy with NO_STRIP
cd src-tauri/target/release/bundle/appimage
NO_STRIP=1 ~/.cache/tauri/linuxdeploy-x86_64.AppImage --appdir Jean.AppDir --output appimage

# Or run the appimage plugin directly
NO_STRIP=1 ~/.cache/tauri/linuxdeploy-plugin-appimage.AppImage --appdir Jean.AppDir
```

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

### Write a New E2E Test with Mocking

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/testing.md

Example of an E2E test using Playwright fixtures for mocking Tauri transport layer.

```typescript
// e2e/tests/my-feature.spec.ts
import { test, activateWorktree } from '../fixtures/tauri-mock'
import { expect } from '@playwright/test'

test.describe('My Feature', () => {
  test('does something', async ({ mockPage }) => {
    // mockPage is a regular Playwright Page with mocks pre-injected
    await activateWorktree(mockPage, 'My Worktree')

    // Interact with the app
    await mockPage.getByRole('button', { name: 'Click me' }).click()
    await expect(mockPage.getByText('Result')).toBeVisible()
  })
})
```

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

### Build and Run WebdriverIO Tests

Source: https://github.com/coollabsio/jean/blob/main/docs/tasks-todo/task-x-e2e-testing-setup.md

First, build the Tauri application in debug mode. Then, run the WebdriverIO tests using the configured `wdio.conf.js` file. This option tests the actual Rust backend.

```bash
bun run tauri:build -- --debug  # Build first
npx wdio run wdio.conf.js
```

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

### Define New Commands

Source: https://github.com/coollabsio/jean/blob/main/src/lib/commands/README.md

Shows how to define new commands, including their ID, label, description, execution logic, and optional availability checks.

```typescript
import { useUIStore } from '@/store/ui-store'
import type { AppCommand } from '@/types/commands'

export const myFeatureCommands: AppCommand[] = [
  {
    id: 'my-action',
    label: 'My Action',
    description: 'Description of what this does',

    execute: context => {
      // Direct store access using getState() pattern
      const currentState = useUIStore.getState()

      // Call actions: context.toggleSidebar()
      // Show feedback: context.showToast('Done!', 'success')
    },

    isAvailable: () => {
      // Optional availability check
      return useUIStore.getState().someCondition
    },
  },
]
```

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

### Rust Tauri Command Logging

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/logging.md

Illustrates logging within a Tauri command function in Rust. This example shows logging before and after an asynchronous operation.

```rust
#[tauri::command]
async fn save_data(data: MyData) -> Result<(), String> {
    log::info!("Saving data for user: {}", data.user_id);

    match save_to_disk(&data).await {
        Ok(_) => {
            log::info!("Data saved successfully");
            Ok(())
        }
        Err(e) => {
            log::error!("Failed to save data: {}", e);
            Err(format!("Save failed: {}", e))
        }
    }
}
```

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

### Register Commands

Source: https://github.com/coollabsio/jean/blob/main/src/lib/commands/README.md

Illustrates how to register newly defined commands into the command system.

```typescript
import { myFeatureCommands } from './my-feature-commands'

export function initializeCommandSystem(): void {
  registerCommands(projectCommands)
  registerCommands(myFeatureCommands) // Add here
}
```

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

### Run Tests and Quality Checks

Source: https://github.com/coollabsio/jean/blob/main/docs/CONTRIBUTING.md

Command to execute all tests and quality checks locally.

```bash
bun run check:all
```

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

### Generate Signing Keys with Tauri CLI

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/releases.md

Use this command to generate a keypair for signing application updates. Ensure the Tauri CLI is installed globally.

```bash
# Install Tauri CLI if not already installed
bun add -g @tauri-apps/cli@next

# Generate keypair
tauri signer generate -w ~/.tauri/myapp.key

# This outputs:
# Private key: (saved to ~/.tauri/myapp.key)
# Public key: dW50cnVzdGVkIGNvbW1lbnQ6...
```

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

### Command Palette Integration

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/command-system.md

Integrate commands into a command palette UI component. This example shows how to fetch and display commands based on search input.

```typescript
// src/components/command-palette/CommandPalette.tsx
export function CommandPalette() {
  const [searchValue, setSearchValue] = useState('')
  const commandContext = useCommandContext()
  const commands = getAllCommands(commandContext, searchValue)

  return (
    <Command>
      <CommandInput value={searchValue} onValueChange={setSearchValue} />
      <CommandList>
        {commands.map(command => (
          <CommandItem
            key={command.id}
            onSelect={() => command.execute(commandContext)}
          >
            {command.icon && <command.icon />}
            <span>{command.label}</span>
            {command.description && <span>{command.description}</span>}
          </CommandItem>
        ))}
      </CommandList>
    </Command>
  )
}
```

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

### Development Pattern: Quality Gates

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/architectural-patterns.md

Execute all quality checks, including linting and tests, using `bun run check:all`. Ensure all checks pass before proceeding with development or deployment.

```bash
bun run check:all  # All checks must pass
```

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

### Manual Bundle Size Analysis

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/bundle-optimization.md

Perform manual analysis by checking output folder sizes and examining asset chunk details in the `dist/assets` directory.

```bash
bun run build
du -sh dist/*
```

```bash
ls -lah dist/assets/
```

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

### Advanced Updater Configuration

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/auto-updates.md

Configure the auto-update system with options for activation, dialog display, update endpoints, installation mode, downgrade allowance, and check interval.

```json
{
  "updater": {
    "active": true,
    "dialog": false,
    "endpoints": ["https://api.example.com/updates"],
    "installMode": "passive",
    "allowDowngrade": false,
    "checkInterval": 3600000
  }
}
```

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

### Define Static Invoke Handlers

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/testing.md

Example of static Tauri command handlers for E2E tests. Every command needs an entry, even if the response is null.

```typescript
// e2e/fixtures/invoke-handlers.ts
export const invokeHandlers: Record<string, unknown> = {
  load_preferences: null, // Overridden by mock-data.ts
  get_worktrees: [], // Overridden by mock-data.ts
  get_sessions: { sessions: [], active_session_id: null },
  rename_session: null,
  send_chat_message: null,
  // ... all other commands
}
```

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

### Define Application Menu in Rust

Source: https://github.com/coollabsio/jean/blob/main/docs/developer/menus.md

Builds the main application menu, including submenus for 'Jean', 'Edit', 'View', and 'Git'. Accelerators are configured for some items, while others are left configurable.

```rust
// src-tauri/src/lib.rs
fn create_app_menu(app: &mut tauri::App) -> Result<(), Box<dyn std::error::Error>> {
    // Build the main application submenu
    let app_submenu = SubmenuBuilder::new(app, "Jean")
        .item(&MenuItemBuilder::with_id("about", "About Jean").build(app)?)
        .separator()
        .item(&MenuItemBuilder::with_id("check-updates", "Check for Updates...").build(app)?)
        .separator()
        .item(
            &MenuItemBuilder::with_id("preferences", "Preferences...")
                .accelerator("CmdOrCtrl+,")
                .build(app)?,
        )
        .separator()
        .item(&PredefinedMenuItem::hide(app, Some("Hide Jean"))?)
        .item(&PredefinedMenuItem::hide_others(app, None)?)
        .item(&PredefinedMenuItem::show_all(app, None)?)
        .separator()
        .item(&PredefinedMenuItem::quit(app, Some("Quit Jean"))?)
        .build()?;

    // Build the Edit submenu with standard clipboard operations
    let edit_submenu = SubmenuBuilder::new(app, "Edit")
        .item(&PredefinedMenuItem::undo(app, None)?)
        .item(&PredefinedMenuItem::redo(app, None)?)
        .separator()
        .item(&PredefinedMenuItem::cut(app, None)?)
        .item(&PredefinedMenuItem::copy(app, None)?)
        .item(&PredefinedMenuItem::paste(app, None)?)
        .item(&PredefinedMenuItem::select_all(app, None)?)
        .build()?;

    // Build the View submenu
    // Note: Accelerators removed since keybindings are user-configurable in preferences
    let view_submenu = SubmenuBuilder::new(app, "View")
        .item(&MenuItemBuilder::with_id("toggle-left-sidebar", "Toggle Left Sidebar").build(app)?)
        .item(&MenuItemBuilder::with_id("toggle-right-sidebar", "Toggle Right Sidebar").build(app)?)
        .build()?;

    // Build the Git submenu
    // Note: Accelerators removed since keybindings are user-configurable in preferences
    let git_submenu = SubmenuBuilder::new(app, "Git")
        .item(&MenuItemBuilder::with_id("open-pull-request", "Open Pull Request...").build(app)?)
        .build()?;

    let menu = MenuBuilder::new(app)
        .item(&app_submenu)
        .item(&edit_submenu)
        .item(&view_submenu)
        .item(&git_submenu)
        .build()?;

    app.set_menu(menu)?;
    Ok(())
}
```