1 files changed, 71 insertions, 0 deletions
diff --git a/packages/tweetdeck/GEMINI.md b/packages/tweetdeck/GEMINI.md
new file mode 100644
index 0000000..c75a387
--- /dev/null
+++ b/packages/tweetdeck/GEMINI.md
@@ -0,0 +1,71 @@
+# Project Context: Bun React TweetDeck
+
+## Overview
+This project is a **TweetDeck-like Twitter client** built with **Bun** and **React 19**. It utilizes Bun's native server and bundler capabilities, bypassing the need for tools like Webpack or Vite. It features a column-based layout for viewing different Twitter feeds (For You, Following, Lists, etc.).
+
+## Tech Stack
+- **Runtime & Bundler:** [Bun](https://bun.com) (v1.3.1+)
+- **Frontend:** React 19, `prosody-ui` (local lib), Lucide React (icons).
+- **Backend:** `Bun.serve()` (Native Bun HTTP server).
+- **Data Fetching:** Custom Twitter API wrapper (`src/lib/fetching/twitter-api.ts`) using cookie-based authentication.
+- **State Persistence:** Custom `usePersistentState` hook.
+
+## Architecture
+The application is a **Hybrid SSR/SPA**:
+1.  **Server (`src/index.ts`):**
+    *   Serves the static `index.html`.
+    *   Provides API endpoints at `/api/twitter/*`.
+    *   Handles Twitter API requests by proxying them with a user-provided cookie.
+2.  **Client (`src/frontend.tsx` -> `src/App.tsx`):**
+    *   Bootstrapped via `src/index.html`.
+    *   Manages the UI state (columns, decks).
+    *   Communicates with the local `/api/twitter` endpoints.
+
+## Key Directories
+- `src/index.ts`: **Server Entry Point**. Defines API routes and serves static files.
+- `src/frontend.tsx`: **Client Entry Point**. Hydrates the React app.
+- `src/App.tsx`: Main application component.
+- `src/components/`: UI components.
+    *   `ColumnBoard.tsx`: Manages the grid/layout of columns.
+    *   `ChatColumn.tsx` / `TimelineColumn.tsx`: Individual feed columns.
+    *   `TweetCard.tsx`: Displays a single tweet.
+- `src/lib/fetching/`: Backend logic for data fetching.
+    *   `twitter-api.ts`: The core service communicating with Twitter.
+- `twatter-cookies.ts`: (Likely) Contains logic or types related to the auth cookie structure.
+
+## Development & Usage
+
+### Prerequisites
+- **Bun** must be installed.
+
+### Commands
+- **Install Dependencies:**
+  ```bash
+  bun install
+  ```
+- **Start Development Server (Hot Reload):**
+  ```bash
+  bun dev
+  ```
+  *Access at `http://localhost:3010`*
+- **Build for Production:**
+  ```bash
+  bun build
+  ```
+  *Outputs to `dist/`*
+- **Start Production Server:**
+  ```bash
+  bun start
+  ```
+
+### Conventions
+- **Bun-First:** Always use `bun` commands (`bun install`, `bun test`, `bun run`). Do not use `npm` or `yarn`.
+- **Styles:** CSS is imported directly into TSX files (e.g., `import './index.css'`).
+- **Local Libs:** The project relies on local libraries (`sortug`, `prosody-ui`) linked via `file:` paths in `package.json`.
+- **Auth:** Authentication is handled via a raw Twitter cookie string passed in API requests.
+
+## Notes for AI Agents
+- When adding new API routes, define them in `src/index.ts`.
+- When modifying the UI, look for components in `src/components/` first.
+- The project uses **React 19**, so use modern React patterns (Hooks, Functional Components).
+- Ensure `bun-python` usage is checked if modifying Python integration files (`tests/python.ts`, `src/lib/fetching/python.ts`).