diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8acdf9c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,128 @@ +# AI Agent Guidelines + +This document provides comprehensive instructions, architectural context, and coding standards for all AI agents (Jules, Cursor, Cline, GitHub Copilot, etc.) working on the Jules Mobile Client codebase. + +**IMPORTANT:** All AI agents must read and strictly adhere to the guidelines in this file before modifying any code. + +--- + +## ๐Ÿ—๏ธ 1. Project Overview & Architecture + +Jules Mobile Client is a React Native/Expo application that acts as a mobile interface for Google's Jules AI coding assistant. + +### Tech Stack +- **Framework:** Expo SDK 54, React Native 0.81 +- **Language:** TypeScript 5.3 (Strict Mode) +- **Routing:** Expo Router 4.x (File-based routing) +- **Package Manager & Runtime:** Bun +- **Styling:** React Native `StyleSheet` (No Tailwind/NativeWind) + +### Directory Structure +``` +โ”œโ”€โ”€ app/ # Expo Router screens & layouts +โ”‚ โ”œโ”€โ”€ (tabs)/ # Main tab navigation +โ”‚ โ”œโ”€โ”€ session/ # Session detail & chat interfaces +โ”‚ โ””โ”€โ”€ _layout.tsx # Root layout with global providers +โ”œโ”€โ”€ components/ +โ”‚ โ”œโ”€โ”€ jules/ # Domain-specific components (AI, chat, sessions) +โ”‚ โ””โ”€โ”€ ui/ # Reusable generic UI components (buttons, text) +โ”œโ”€โ”€ constants/ +โ”‚ โ”œโ”€โ”€ theme.ts # Color tokens, typography, spacing +โ”‚ โ”œโ”€โ”€ i18n.ts # Localization dictionaries (en/ja) +โ”‚ โ””โ”€โ”€ types.ts # Shared TypeScript interfaces +โ”œโ”€โ”€ hooks/ # Custom React hooks (API, storage, theme) +โ”œโ”€โ”€ utils/ # Helper functions +โ””โ”€โ”€ docs/ # Comprehensive project documentation +``` + +--- + +## ๐Ÿค– 2. General Agent Workflow + +When assigned a task, follow this exact workflow: + +1. **Explore First:** Never write code blindly. Use `grep`, `find`, or read relevant files (`app/`, `components/`, `hooks/`) to understand the current implementation. +2. **Read the Docs:** Check the `docs/` directory for specific feature or API documentation before implementing new logic. +3. **Plan:** Formulate a step-by-step plan. Identify all files that will be affected. +4. **Implement Incrementally:** Make small, focused changes. Verify syntax and logic after each file change. +5. **Test Thoroughly:** Use `bun test` to verify changes. Update or write new tests if applicable. +6. **Self-Review:** Ensure your changes adhere to the "Coding Standards" below. + +--- + +## ๐Ÿ’ป 3. Coding Standards & Conventions + +### 3.1. TypeScript & React Patterns +- **Strict Typing:** No `any`. Use interfaces and types from `constants/types.ts`. +- **Functional Components:** Use React Functional Components with hooks. +- **Props:** Component props must extend React Native primitives when wrapping them (e.g., `interface ThemedTextProps extends TextProps`). +- **Memoization:** Use `useMemo` and `useCallback` judiciously, especially for list items and heavy computations. Combine chained `.filter()` or `.map()` operations into single passes where possible. + +### 3.2. Styling & Theming +- **Strict Theme Adherence:** Hardcoded colors (e.g., `#FFFFFF`, `rgba(0,0,0,0.5)`) are strictly forbidden. You **must** use the `colors` object from the theme system. +- **Dark Mode Support:** Every new UI element must support both light and dark modes. Use the `useColorScheme` hook. + ```tsx + const colorScheme = useColorScheme(); + const isDark = colorScheme === 'dark'; + + ``` +- **Shared Styles:** Extract common styles. Use `StyleSheet.create()`. + +### 3.3. Internationalization (i18n) +- **No Hardcoded Strings:** User-facing text must be localized. +- **Usage:** Use the `t()` function from `useI18n()`. +- **Updating Dictionaries:** Whenever adding a new string, you must add it to *both* the `en` and `ja` objects in `constants/i18n.ts`. + +### 3.4. UI/UX Guidelines +- **Skeleton Loading:** Do not use full-screen spinners. Use Skeleton components (e.g., `SessionCardSkeleton`, `ActivityItemSkeleton`) with `Animated.Value` for shimmer effects. +- **Haptic Feedback:** Use `expo-haptics` for meaningful user interactions (e.g., success, error, selection). +- **Icons:** Use the `IconSymbol` component from `components/ui/icon-symbol.tsx` which maps SF Symbols (iOS) to Material Icons (Android/Web). + +### 3.5. State & Data Management +- **API Calls:** All communication with the Jules API must go through the centralized hooks in `hooks/use-jules-api.ts`. Do not use raw `fetch` in components. +- **Secure Storage:** Sensitive data (like API keys) must be stored using `expo-secure-store` via the `use-secure-storage.ts` hook. Do not use `AsyncStorage`. + +--- + +## ๐Ÿงช 4. Testing Rules (Bun Test) + +This project uses `bun:test` and `@testing-library/react-native`. + +1. **Mocking React Native:** When testing modules that import `react-native`, you must mock it **before** importing the target module: + ```typescript + import { mock } from "bun:test"; + mock.module('react-native', () => ({ + default: { View: 'View', Text: 'Text' }, + View: 'View', + Text: 'Text', + StyleSheet: { create: (s: any) => s } + })); + ``` +2. **Global Mocks:** Avoid globally mocking `react` (e.g., `mock.module('react', ...)`), as it bleeds across concurrent test files and causes `SyntaxError: Missing 'default' export`. +3. **Idiomatic Testing:** Write standard RTL tests (`render`, `fireEvent`, `screen`). Do not write hacky functional workarounds. +4. **Running Tests:** + - Run all: `bun test` + - Run specific: `bun test ./path/to/file.test.tsx` (Use `./` prefix) + +--- + +## ๐Ÿ› ๏ธ 5. Standard Commands + +Agents should execute these commands via the terminal sandbox when verifying work: + +- **Install deps:** `bun install` (Never use `bun install ` for existing dependencies to avoid unintended version bumps. Just `bun install` to respect the lockfile.) +- **Run Tests:** `bun test` +- **Lint:** `bun lint` +- **Typecheck:** `bun oxc` or `bun run typecheck` + +--- + +## โš ๏ธ 6. Common Pitfalls to Avoid + +- **Circular Dependencies:** Do not export shared utility components/functions from Expo Router entry files (`app/**/*.tsx`). Move them to `components/` or `utils/`. +- **API URL Formatting:** When calling Jules API endpoints, construct the full resource name exactly (e.g., `sessions/{session_id}/activities/{activity_id}`). +- **Static Web Builds:** Visual verification of UI changes via Playwright fails on `expo export` if Metro isn't configured. Start the dev server directly (`bun web > output.log 2>&1 &`) and wait for `localhost:8081`. +- **Over-Mucking the Environment:** If tests fail, diagnose the code first. Do not try to randomly install/uninstall packages or alter `package.json` unless explicitly required. + +--- +*End of Agent Instructions. Proceed with your task.* diff --git a/README.ja.md b/README.ja.md index 5a42a1b..271313e 100644 --- a/README.ja.md +++ b/README.ja.md @@ -28,11 +28,11 @@

๐Ÿ‡บ๐Ÿ‡ธ English โ€ข - ๐Ÿ“ ใ‚ขใƒผใ‚ญใƒ†ใ‚ฏใƒใƒฃ โ€ข - ๐Ÿ”Œ API ใƒชใƒ•ใ‚กใƒฌใƒณใ‚น โ€ข - ๐ŸŽฏ ใƒขใƒผใƒ‰้ธๆŠž โ€ข - ๐Ÿค– ใ‚จใƒผใ‚ธใ‚งใƒณใƒˆใ‚ฌใ‚คใƒ‰ โ€ข - โ“ FAQ โ€ข + ๐Ÿ“ ใ‚ขใƒผใ‚ญใƒ†ใ‚ฏใƒใƒฃ โ€ข + ๐Ÿ”Œ API ใƒชใƒ•ใ‚กใƒฌใƒณใ‚น โ€ข + ๐ŸŽฏ ใƒขใƒผใƒ‰้ธๆŠž โ€ข + ๐Ÿค– ใ‚จใƒผใ‚ธใ‚งใƒณใƒˆใ‚ฌใ‚คใƒ‰ โ€ข + โ“ FAQ โ€ข ๐Ÿค ่ฒข็Œฎ

@@ -186,7 +186,7 @@ jules-mobile-client/ - **ใ‚ขใ‚ฏใƒ†ใ‚ฃใƒ“ใƒ†ใ‚ฃ่กจ็คบ** - ใƒใƒผใƒชใƒณใ‚ฐใซใ‚ˆใ‚‹ใƒชใ‚ขใƒซใ‚ฟใ‚คใƒ ใƒใƒฃใƒƒใƒˆๅฑฅๆญด - **ใƒ—ใƒฉใƒณๆ‰ฟ่ช** - AI็”Ÿๆˆใƒ—ใƒฉใƒณใฎ็ขบ่ช -่ฉณ็ดฐใฏ[APIใƒชใƒ•ใ‚กใƒฌใƒณใ‚น](docs/API.md)ใ‚’ๅ‚็…งใ€‚ +่ฉณ็ดฐใฏ[APIใƒชใƒ•ใ‚กใƒฌใƒณใ‚น](docs/api/reference.md)ใ‚’ๅ‚็…งใ€‚ ## ๏ธ ๆŠ€่ก“ใ‚นใ‚ฟใƒƒใ‚ฏ diff --git a/README.md b/README.md index 474f67d..56613ea 100644 --- a/README.md +++ b/README.md @@ -28,12 +28,12 @@

๐Ÿ‡ฏ๐Ÿ‡ต ๆ—ฅๆœฌ่ชž โ€ข - ๐Ÿ“ Architecture โ€ข - ๐Ÿ”Œ API โ€ข - ๐ŸŽฏ Modes โ€ข - ๐Ÿ” Security โ€ข - ๐Ÿš€ Production โ€ข - โ“ FAQ + ๐Ÿ“ Architecture โ€ข + ๐Ÿ”Œ API โ€ข + ๐ŸŽฏ Modes โ€ข + ๐Ÿ” Security โ€ข + ๐Ÿš€ Production โ€ข + โ“ FAQ

--- @@ -207,7 +207,7 @@ The app integrates with the [Jules API](https://jules.googleapis.com/v1alpha) to - **View Activities** - Real-time chat history with polling - **Approve Plans** - Confirm AI-generated plans -See [API Reference](docs/API.md) for detailed documentation. +See [API Reference](docs/api/reference.md) for detailed documentation. ## ๐Ÿ› ๏ธ Tech Stack @@ -250,8 +250,8 @@ eas build --platform ios --profile production Having issues? Check our comprehensive troubleshooting guide: -- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions -- **[FAQ](docs/FAQ.md)** - Frequently asked questions +- **[Troubleshooting Guide](docs/guides/troubleshooting.md)** - Common issues and solutions +- **[FAQ](docs/guides/faq.md)** - Frequently asked questions ### Quick Fixes @@ -270,16 +270,16 @@ bun run reset-project | Document | Description | |----------|-------------| -| [FAQ](docs/FAQ.md) | Frequently asked questions | -| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common issues and solutions | -| [Architecture](docs/ARCHITECTURE.md) | App architecture overview | -| [API Reference](docs/API.md) | Jules API integration details | -| [Components](docs/COMPONENTS.md) | Component documentation | -| [Development](docs/DEVELOPMENT.md) | Development setup guide | -| [Mode Selection](docs/MODE_SELECTION.md) | Start vs Review modes | -| [Security](docs/SECURITY.md) | Security best practices | -| [Production Deployment](docs/PRODUCTION.md) | Production deployment guide | -| [Agent Guide](docs/Agent.md) | Guide for AI agents | +| [FAQ](docs/guides/faq.md) | Frequently asked questions | +| [Troubleshooting](docs/guides/troubleshooting.md) | Common issues and solutions | +| [Architecture](docs/architecture/overview.md) | App architecture overview | +| [API Reference](docs/api/reference.md) | Jules API integration details | +| [Components](docs/architecture/components.md) | Component documentation | +| [Development](docs/guides/development.md) | Development setup guide | +| [Mode Selection](docs/features/mode-selection.md) | Start vs Review modes | +| [Security](docs/deployment/security.md) | Security best practices | +| [Production Deployment](docs/deployment/production.md) | Production deployment guide | +| [Agent Guide](AGENTS.md) | Guide for AI agents | | [Contributing](CONTRIBUTING.md) | How to contribute | ## ๐Ÿค Contributing @@ -363,7 +363,7 @@ This project is licensed under the **BSD 2-Clause License** - see the [LICENSE]( - Implement proper API key management for teams - Set up monitoring and rate limiting -See [docs/SECURITY.md](docs/SECURITY.md) for security best practices. +See [docs/deployment/security.md](docs/deployment/security.md) for security best practices. ## ๐Ÿ™ Acknowledgments diff --git a/docs/Agent.md b/docs/Agent.md deleted file mode 100644 index 4372820..0000000 --- a/docs/Agent.md +++ /dev/null @@ -1,268 +0,0 @@ -# Agent Instructions - -This document provides instructions for AI agents working on the Jules Mobile Client codebase. - -## Project Overview - -Jules Mobile Client is a React Native/Expo application that provides a mobile interface for Google's Jules AI coding assistant. The app allows users to: - -- View and manage coding sessions -- Create new tasks for Jules to work on -- Chat with Jules AI in real-time -- Approve AI-generated plans - -## Tech Stack - -| Technology | Version | Purpose | -|------------|---------|---------| -| Expo SDK | 54 | React Native framework | -| React Native | 0.81 | Mobile UI | -| TypeScript | 5.3 | Type safety | -| Expo Router | 4.x | File-based routing | -| Bun | latest | Package manager & runtime | - -## Key Directories - -``` -app/ # Screens (Expo Router) -โ”œโ”€โ”€ (tabs)/ # Tab navigation -โ”‚ โ”œโ”€โ”€ index.tsx # Sessions list -โ”‚ โ”œโ”€โ”€ settings.tsx # Settings -โ”‚ โ””โ”€โ”€ explore.tsx # (unused) -โ”œโ”€โ”€ session/[id].tsx # Session detail/chat -โ”œโ”€โ”€ create-session.tsx # New task creation -โ””โ”€โ”€ _layout.tsx # Root layout with providers - -components/ -โ”œโ”€โ”€ jules/ # Jules-specific components -โ”‚ โ”œโ”€โ”€ activity-item.tsx # Chat messages + skeleton -โ”‚ โ”œโ”€โ”€ session-card.tsx # Session cards + skeleton -โ”‚ โ”œโ”€โ”€ loading-overlay.tsx # Loading indicator -โ”‚ โ”œโ”€โ”€ code-block.tsx # Syntax highlighting -โ”‚ โ””โ”€โ”€ data-renderer.tsx # Debug data display -โ””โ”€โ”€ ui/ # Generic UI components - -constants/ -โ”œโ”€โ”€ types.ts # TypeScript interfaces -โ”œโ”€โ”€ i18n.ts # Translations (ja/en) -โ”œโ”€โ”€ i18n-context.tsx # i18n React context -โ”œโ”€โ”€ api-key-context.tsx # API key context -โ””โ”€โ”€ theme.ts # Colors - -hooks/ -โ”œโ”€โ”€ use-jules-api.ts # Jules API communication -โ”œโ”€โ”€ use-secure-storage.ts # Secure data persistence -โ”œโ”€โ”€ use-color-scheme.ts # Theme detection -โ””โ”€โ”€ use-theme-color.ts # Theme colors -``` - -## Important Patterns - -### 1. API Communication - -All Jules API calls go through `hooks/use-jules-api.ts`: - -```typescript -const { - isLoading, - error, - fetchSessions, - fetchActivities, - createSession, - approvePlan -} = useJulesApi({ apiKey, t }); -``` - -### 2. Internationalization (i18n) - -Use the `useI18n` hook for translations: - -```typescript -const { t, language, setLanguage } = useI18n(); -// Usage: t('keyName') -``` - -Add new keys to both `ja` and `en` objects in `constants/i18n.ts`. - -### 3. Skeleton Loading - -Use skeleton components instead of loading overlays for modern UX: - -```typescript -// Sessions list -{isLoading ? ( - <> - - - -) : ( - sessions.map(s => ) -)} - -// Activity list -{isLoading ? ( - <> - - - -) : ( - activities.map(a => ) -)} -``` - -### 4. Dark Mode - -Always support dark mode: - -```typescript -const colorScheme = useColorScheme(); -const isDark = colorScheme === 'dark'; - - -``` - -### 5. Secure Storage - -API keys and sensitive data use expo-secure-store: - -```typescript -const { saveApiKey, getApiKey } = useSecureStorage(); -``` - -## Jules API Reference - -Base URL: `https://jules.googleapis.com/v1alpha` - -### Endpoints Used - -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/sources` | GET | List connected repositories | -| `/sessions` | GET | List all sessions | -| `/sessions` | POST | Create new session | -| `/sessions/{id}/activities` | GET | Get session activities | -| `/sessions/{id}:approvePlan` | POST | Approve a plan | - -### Create Session Request Body - -```json -{ - "prompt": "User's task description", - "sourceContext": { - "source": "sources/github/owner/repo", - "githubRepoContext": { - "startingBranch": "main" - } - }, - "title": "Short title..." -} -``` - -## Common Tasks - -### Adding a New Translation - -1. Add key to `constants/i18n.ts` in both `ja` and `en` objects -2. Use `t('newKey')` in components - -### Adding a New Screen - -1. Create file in `app/` directory -2. Export default function component -3. Add to navigation if needed - -### Creating a New Component - -1. Create in `components/jules/` for Jules-specific, `components/ui/` for generic -2. Export from `components/jules/index.ts` if Jules component -3. Support dark mode with `useColorScheme` - -### Adding Skeleton Loading - -1. Create skeleton component with shimmer animation -2. Use `Animated.Value` for opacity animation -3. Match layout of actual component - -## Code Style - -- Use functional components with hooks -- TypeScript strict mode enabled -- Use `StyleSheet.create` for styles -- Prefer Bun over npm/yarn -- No `any` types - use proper interfaces from `constants/types.ts` - -## Bun Commands - -This project uses Bun as the primary runtime and package manager. - -### Essential Commands - -```bash -# Install dependencies -bun install - -# Start development server -bun start - -# Run on specific platforms -bun ios # iOS Simulator -bun android # Android Emulator -bun web # Web browser - -# Install Expo-compatible packages -bunx expo install - -# Example: Add reanimated -bunx expo install react-native-reanimated - -# Linting -bun lint -``` - -# type-checking -```bash -bun oxc -``` - -### Why Bun? - -1. **Faster installs** - Much faster than npm/yarn -2. **Built-in TypeScript** - No compilation needed -3. **Auto .env loading** - No dotenv required -4. **npm compatible** - Works with node_modules - -### Important Notes - -- Always use `bunx expo install` for React Native packages (ensures version compatibility) -- Use `bun add` for non-Expo packages -- Bun automatically loads `.env` files - -## Testing - -```bash -# Run tests -bun test - -# Type check -bun run typecheck -``` - -## Building - -```bash -# Development -bun start - -# Android build -eas build --platform android - -# iOS build -eas build --platform ios -``` - -## Debugging Tips - -1. Check `console.log` output in Metro bundler -2. API errors are logged with full response body -3. Use `DataRenderer` component to inspect data structures -4. Enable React Native Debugger for component inspection diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b8b9e0b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,29 @@ +# Jules Mobile Client Documentation + +Welcome to the documentation for the Jules Mobile Client. This directory contains detailed guides and reference materials to help you understand, develop, and deploy the application. + +## ๐Ÿ“š Table of Contents + +### ๐Ÿ“ Architecture & Design +- [Architecture Overview](architecture/overview.md) +- [Component Documentation](architecture/components.md) + +### ๐Ÿ”Œ API Reference +- [Jules API Reference](api/reference.md) + +### โœจ Features +- [Mode Selection (Start vs Review)](features/mode-selection.md) +- [Session Management](features/session-management.md) +- [Chat Interface](features/chat-interface.md) + +### ๐Ÿš€ Deployment & Security +- [Production Deployment](deployment/production.md) +- [Security Guidelines](deployment/security.md) + +### ๐Ÿ“– Guides +- [Development Setup](guides/development.md) +- [Troubleshooting](guides/troubleshooting.md) +- [FAQ](guides/faq.md) + +## ๐Ÿค– AI Agents +If you are an AI agent contributing to this repository, please read the [AGENTS.md](../AGENTS.md) file in the repository root for comprehensive instructions. diff --git a/docs/API.md b/docs/api/reference.md similarity index 100% rename from docs/API.md rename to docs/api/reference.md diff --git a/docs/COMPONENTS.md b/docs/architecture/components.md similarity index 100% rename from docs/COMPONENTS.md rename to docs/architecture/components.md diff --git a/docs/ARCHITECTURE.md b/docs/architecture/overview.md similarity index 100% rename from docs/ARCHITECTURE.md rename to docs/architecture/overview.md diff --git a/docs/PRODUCTION.md b/docs/deployment/production.md similarity index 100% rename from docs/PRODUCTION.md rename to docs/deployment/production.md diff --git a/docs/SECURITY.md b/docs/deployment/security.md similarity index 100% rename from docs/SECURITY.md rename to docs/deployment/security.md diff --git a/docs/features/chat-interface.md b/docs/features/chat-interface.md new file mode 100644 index 0000000..6085215 --- /dev/null +++ b/docs/features/chat-interface.md @@ -0,0 +1,31 @@ +# Chat Interface + +The Chat Interface is the core screen for interacting with Jules during a session (`app/session/[id].tsx`). + +## Overview + +The interface provides a real-time, chronological view of the session's activities. It displays messages, code blocks, plan proposals, and state changes. + +## Component Structure + +The main component is `ActivityItem` (`components/jules/activity-item.tsx`), which renders individual activities based on their type: + +### 1. User Prompts +Displays the initial prompt provided by the user when creating the session. + +### 2. Jules Responses (Markdown & Code) +Jules' responses are parsed and rendered using `react-native-markdown-display`. Code blocks are syntax-highlighted using the `CodeBlock` component (`components/jules/code-block.tsx`), which supports horizontal scrolling for long lines. + +### 3. Plan Approvals +If the session was created in "Review" mode, Jules will output a proposed plan. The interface provides interactive buttons to "Approve" or "Reject" the plan. + +### 4. State Transitions +Changes in the session state (e.g., "Jules started planning", "Jules finished the task") are displayed as inline informational messages. + +## Real-time Polling + +To ensure the chat is always up-to-date, the application uses a polling mechanism via the `useJulesApi` hook. It regularly calls the `GET /sessions/{id}/activities` endpoint to fetch new messages. + +## Skeleton Loading + +When opening a session or waiting for initial data, the interface displays placeholder UI (`ActivityItemSkeleton`) with shimmer animations instead of a simple loading spinner, providing a modern and smooth user experience. diff --git a/docs/MODE_SELECTION.md b/docs/features/mode-selection.md similarity index 100% rename from docs/MODE_SELECTION.md rename to docs/features/mode-selection.md diff --git a/docs/features/session-management.md b/docs/features/session-management.md new file mode 100644 index 0000000..9e564bf --- /dev/null +++ b/docs/features/session-management.md @@ -0,0 +1,43 @@ +# Session Management + +The Jules Mobile Client provides a robust interface for managing coding sessions with the Jules AI. + +## Session Lifecycle + +A session goes through various states, represented by distinct badges in the UI: + +1. **Queued:** The session has been created and is waiting to be processed by Jules. +2. **Planning:** Jules is analyzing the prompt and source context to formulate a plan. +3. **In Progress:** Jules is actively executing the plan and making changes. +4. **Completed:** Jules has finished the task. +5. **Failed:** An error occurred during the session. + +## Features + +### 1. Creating a Session +Users can start a new task by navigating to the "New Task" screen (`app/create-session.tsx`). +- **Prompt:** A detailed description of the task. +- **Repository Context:** Select a GitHub repository from the connected sources. +- **Mode:** Choose between "Start" (auto-execute) or "Review" (manual plan approval) modes. See [Mode Selection](mode-selection.md) for more details. + +### 2. Searching & Filtering +The main "Sessions" tab provides tools to find specific sessions: +- **Search:** Quickly find sessions by typing keywords in the title or ID. +- **Filter:** View only active (In Progress, Queued, Planning), Completed, or Failed sessions. +- **Sort:** Order sessions by the most recent update or alphabetically by title. + +### 3. Session Cards +Each session is displayed as a card (`components/jules/session-card.tsx`) showing: +- Title and ID +- Current status badge +- Last updated timestamp +- Repository context + +### 4. Exporting Sessions +Users can export a session's history for sharing or archiving: +- Format options: Markdown (.md) or JSON (.json) +- The export includes all activities, prompts, and plans within the session. + +## Internal Mechanics + +Session data is fetched using the `useJulesApi` hook, which interacts with the `GET /sessions` endpoint. The list is heavily optimized using memoization (`useMemo`) to ensure smooth scrolling even with a large number of sessions. diff --git a/docs/DEVELOPMENT.md b/docs/guides/development.md similarity index 100% rename from docs/DEVELOPMENT.md rename to docs/guides/development.md diff --git a/docs/FAQ.md b/docs/guides/faq.md similarity index 100% rename from docs/FAQ.md rename to docs/guides/faq.md diff --git a/docs/TROUBLESHOOTING.md b/docs/guides/troubleshooting.md similarity index 100% rename from docs/TROUBLESHOOTING.md rename to docs/guides/troubleshooting.md