feat: add docusaurus

.cursor/rules/docusaurus-development.mdc

@@ -0,0 +1,37 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Docusaurus Development Rules
+
+## Development Server
+- **Do NOT launch Docusaurus development server** during development sessions
+- The user typically has Docusaurus running already and can see live changes
+- File changes are automatically detected and hot-reloaded
+- Focus on making file changes rather than testing server startup
+
+## File Structure
+- Custom CSS goes in `docs/src/css/custom.css`
+- Configuration in `docs/docusaurus.config.ts`
+- Content pages in `docs/docs/` directory
+- Static assets in `docs/static/` directory
+
+## Theme Customization
+- Use CSS custom properties (CSS variables) for theme consistency
+- Support both light and dark modes with `[data-theme="dark"]` selectors
+- Match color scheme from main app `src/app/globals.css` when possible
+- Prioritize readability and accessibility over visual flair
+- Keep performance in mind - avoid heavy animations or complex effects
+
+## Common Issues to Watch For
+- Button text visibility in dark mode
+- Contrast ratios for accessibility
+- Mobile responsiveness
+- Code block styling consistency
+- Navigation element visibility
+
+## Testing Approach
+- Make incremental changes to CSS/config files
+- User will verify changes in their running development server
+- Focus on iterative improvements rather than wholesale rewrites

.gitignore

@@ -60,4 +60,13 @@ node_modules/
 # OS specific
 # Task files
 tasks.json
-tasks/ 
+tasks/
+
+# Docusaurus
+/docs/build
+/docs/.docusaurus
+/docs/.cache
+/docs/node_modules
+/docs/bun.lockb
+/docs/package-lock.json
+/docs/api 

config/pipeline.config.ts

@@ -384,4 +384,4 @@ export default {
     Decentralization & Open Collaboration: AI systems should move beyond centralized control towards distributed intelligence and community-driven progress.
     `,
   },
-} as const satisfies PipelineConfig;
+} satisfies PipelineConfig;

docs/docs/advanced/auth-worker.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 5
+---
+
+# Authentication (`/auth-worker`)
+
+The `/auth-worker` directory contains a [Cloudflare Worker](https://workers.cloudflare.com/) that handles the server-side logic for our GitHub authentication process. Using a serverless worker provides a secure and scalable way to manage OAuth credentials and user tokens without maintaining a traditional backend server.
+
+## Purpose and Workflow
+
+The primary responsibility of this worker is to facilitate the OAuth 2.0 flow with GitHub.
+
+1.  **Initiation**: When a user clicks the "Login with GitHub" button on the frontend, they are redirected to GitHub's authorization page.
+2.  **Callback**: After the user approves the authorization request, GitHub redirects them back to a specific endpoint handled by this Cloudflare Worker (`/auth/callback`).
+3.  **Token Exchange**: The worker receives a temporary `code` from GitHub. It then securely exchanges this code for a permanent `access_token` by making a server-to-server request to GitHub's token endpoint, using the client ID and client secret stored as secure environment variables in the Cloudflare dashboard.
+4.  **Redirection**: Once the worker has obtained the access token, it redirects the user back to the main application, passing the token along so the frontend can store it and make authenticated requests on the user's behalf.
+
+## Key Files
+
+- **`src/index.ts`**: This is the main entry point for the worker. It contains the logic for handling the callback request, exchanging the code for a token, and managing the final redirection.
+- **`wrangler.toml`**: This is the configuration file for the Cloudflare Worker, defining its name, compatibility date, and other settings.
+- **`package.json`**: Defines the dependencies for the worker, which are typically minimal.
+
+By isolating this sensitive logic in a serverless worker, we keep our client-side application clean and ensure that our OAuth client secret is never exposed to the browser.

docs/docs/advanced/automation.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+---
+
+# Automation Strategy
+
+The project relies heavily on GitHub Actions for automation, ensuring that data is always up-to-date and the website reflects the latest contributions. Our CI/CD strategy is built around a few key workflows.
+
+## Core Workflows
+
+### 1. `run-pipelines.yml`
+
+This is the main data processing workflow, scheduled to run daily. Its job is to:
+
+- Fetch the latest GitHub data from the configured repositories.
+- Run the full `ingest → process → export → summarize` pipeline chain.
+- Commit the newly generated data (JSON files, markdown summaries, and the updated database dump) to the `_data` branch.
+
+This workflow can also be triggered manually from the GitHub Actions tab, which allows for running the pipeline with custom date ranges or forcing the regeneration of existing data.
+
+### 2. `deploy.yml`
+
+This workflow is responsible for building and deploying the website to GitHub Pages. It is triggered:
+
+- On every push to the `main` branch.
+- Manually, for on-demand deployments.
+- Automatically, after a successful run of the `run-pipelines.yml` workflow.
+
+Before building the site, this workflow checks out the latest data from the `_data` branch, ensuring that the deployed website is always synchronized with the latest analytics.
+
+### 3. `pr-checks.yml`
+
+This workflow serves as a quality gate for all pull requests. It runs a series of checks to maintain code quality and prevent regressions:
+
+- **Linting and Typechecking**: Ensures all new code adheres to the project's style and type standards.
+- **Build Verification**: Confirms that the application builds successfully with the proposed changes.
+- **Pipeline Test**: Runs the data pipeline on a small, controlled sample of data to ensure its integrity.
+- **Migration Verification**: Checks if schema changes are accompanied by the necessary migration files.
+
+These workflows work together to create a robust, automated system for data management and deployment.

docs/docs/advanced/frontend-src.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 3
+---
+
+# Frontend Guide (`/src`)
+
+A frontend developer contributing to this system would primarily need to be familiar with the **Next.js application structure** within the `src/app/` directory and the **React components** within the `src/components/` directory, along with several utility and data access files in `src/lib/`.
+
+Here's a breakdown of key areas and files:
+
+## 1. Next.js Application Structure (`src/app/`)
+
+This directory uses the **Next.js App Router** and contains the pages that render the UI. Understanding how routing works here is crucial.
+
+- **Root Layout (`src/app/layout.tsx`)**: Defines the overall structure, including shared components like the `Navigation` and providers like `ThemeProvider` and `AuthProvider`.
+- **Global Styles (`src/app/globals.css`)**: Contains the base styles, including Tailwind CSS configurations and color variables.
+- **Page Files (`src/app/.../page.tsx`)**: These are the entry points for different routes. They often fetch data (in server components) and pass it to client components for rendering.
+  - **Homepage (`src/app/page.tsx`)**: Currently redirects to the daily summary page (`/day`).
+  - **About Page (`src/app/about/page.tsx`)**: Contains static content about the project's vision, problem, solution, and tech stack. It uses the `ProgressSection` component.
+  - **Auth Callback Page (`src/app/auth/callback/page.tsx`)**: Handles the GitHub OAuth callback process using the `useAuth` hook from the context.
+  - **Leaderboard Page (`src/app/leaderboard/page.tsx`)**: Fetches leaderboard data for different periods (`all`, `monthly`, `weekly`) and renders the `Leaderboard` component.
+  - **Interval Summary Pages (`src/app/[interval]/[[...date]]/page.tsx`)**: Handles routes like `/day/YYYY-MM-DD` or `/month/YYYY-MM`. It fetches metrics and summaries for a specific time interval and renders components like `DateNavigation`, `StatCardsDisplay`, `SummaryContent`, `CodeChangesDisplay`, and `LlmCopyButton`.
+  - **Profile Page (`src/app/profile/[username]/page.tsx`)**: Fetches a specific user's profile data (scores, tags, summaries, activity) and renders the `UserProfile` component. Includes server-side data fetching queries.
+  - **Profile Edit Page (`src/app/profile/edit/page.tsx`)**: Contains components for editing a user's profile, specifically linking wallet addresses. Uses client components like `ProfileEditor`.
+- **Query Files (`src/app/.../queries.ts`)**: These files contain database query logic used by Next.js server components to fetch data needed for rendering pages. This is where the frontend interacts with the data layer.
+
+## 2. React Components (`src/components/`)
+
+This directory houses reusable UI components used across the application.
+
+- **Shadcn UI Components (`src/components/ui/`)**: Pre-built UI components like `Button`, `Card`, `Dialog`, `DropdownMenu`, `Input`, `Select`, `Tabs`, `Tooltip`, etc.. Familiarity with these components and how they are used is essential. Includes custom wrappers like `WalletAddressBadge` and `LlmCopyButton`.
+- **Core Application Components (`src/components/`)**: Components specific to this application's features.
+  - `Navigation.tsx`: The main site navigation bar.
+  - `Leaderboard.tsx` and `LeaderboardCard.tsx`: Components for displaying the leaderboard list and individual entries.
+  - `UserProfile.tsx`: The main component for displaying a contributor's profile.
+  - `SummaryCard.tsx`: Component to display AI-generated summaries with navigation.
+  - `StatCard.tsx`: A generic card component for displaying a key statistic, often with an icon and optional modal content.
+  - `DailyActivity.tsx`: Component to visualize a user's daily activity using a bar chart.
+  - `SkillCard.tsx`: Component to display a contributor's skill or tag level and progress.
+  - `ActivityItem.tsx`, `ContributorItem.tsx`, `MetricItem.tsx`, `StatBadge.tsx`, `BadgeList.tsx`, `CounterWithIcon.tsx`: Smaller presentation components used within pages or other cards.
+  - `AuthControls.tsx`: Component to handle user authentication UI (Login/Logout/Profile link).
+  - Icon components (`EthereumIcon.tsx`, `SolanaIcon.tsx`).
+- **Page-Specific Components (`src/app/.../components/`)**: Components used specifically within one page, such as `DateNavigation`, `IntervalSelector`, `StatCardsDisplay`, `SummaryContent`, `CodeChangesDisplay`, and the modal content components for lists. Also includes wallet linking components like `ProfileEditor`, `WalletLinkForm`, `WalletLinkBoard`, and `ProfileRepoNotice`.
+
+## 3. Frontend Utility and Helper Files (`src/lib/`)
+
+- `src/lib/utils.ts`: General utility functions like `cn` for conditionally combining CSS class names.
+- `src/lib/date-utils.ts`: Functions for formatting and manipulating dates, used extensively for UI display.
+- `src/lib/format-number.ts`: Utility for formatting large numbers concisely.
+- `src/lib/skill-icons.tsx`: Maps skill names to corresponding Lucide icons for display.
+- `src/lib/typeHelpers.ts`: Basic TypeScript type guards.
+- `src/lib/data/db-nextjs.ts`: Provides the Drizzle ORM database instance for use in Next.js server components.
+- `src/lib/data/schema.ts`: Defines the database schema. Understanding this is necessary to know what data is available and how it's structured for querying.
+- `src/lib/walletLinking/`: Contains hooks (`useProfileEditor.ts`, `useProfileWallets.ts`) and utility functions (`readmeUtils.ts`, `getUserWalletAddresses.ts`) related to the wallet linking feature, which is part of the frontend profile editing functionality. `decode.ts` is used here for Base64 decoding.
+- `src/lib/llm-formatter.ts`: Used by the `LlmCopyButton` to format metrics data for copying.
+- `src/hooks/useCopyToClipboard.ts`: Custom hook used in the wallet linking components.
+
+## 4. Context and Hooks (`src/contexts/`, `src/hooks/`)
+
+- `src/contexts/AuthContext.tsx`: Provides authentication state (`user`, `token`) and functions (`signin`, `signout`, `handleAuthCallback`) via the `useAuth` hook. Crucial for any authenticated features.
+- `src/hooks/useCopyToClipboard.ts`: A specific custom hook for copying text.
+
+In summary, a frontend developer should focus heavily on the files within `src/app/` and `src/components/`, understanding how the Next.js App Router fetches data (often via queries in `src/app/.../queries.ts` and `src/lib/scoring/queries.ts`) and how the various components display this data. Familiarity with core utilities in `src/lib/` (especially date formatting, number formatting, and shared types/helpers) and state management like the `AuthContext` is also vital. While not writing pipeline code, understanding the structure of the generated data and the database schema (`src/lib/data/schema.ts`) is necessary to effectively query and display information.

docs/docs/advanced/pipelines.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 4
+---
+
+# Pipelines
+
+The `/cli` directory contains the entry points for the command-line interface that drives the data pipeline. These scripts use the `commander.js` library to parse command-line arguments and orchestrate the different pipeline stages defined in `/src/lib/pipelines`.
+
+## Key Scripts
+
+### `analyze-pipeline.ts`
+
+This is the main script for running the entire data processing pipeline. It orchestrates the various stages of data handling:
+
+- **Ingestion**: It fetches data from the GitHub API. You can specify date ranges, the number of days, or force a full re-ingestion.
+- **Processing**: It analyzes the raw data, calculates contributor scores based on the rules in `pipeline.config.ts`, and identifies expertise areas.
+- **Exporting**: It generates structured JSON files of the processed data, which are used by the frontend.
+- **Summarization**: It leverages AI to create human-readable summaries of both project-wide and individual contributor activity.
+
+This script is highly configurable via command-line flags, which are detailed in the [Command Reference](../developer-guides/command-reference.md).
+
+### `data-sync.ts`
+
+This script is a utility for managing the project's data, particularly for new contributors or for synchronizing environments. Its primary functions are:
+
+- **Syncing from Production**: It can fetch the latest data from the `_data` branch of the repository. This includes all historical stats, summaries, and the SQLite database dump. This is the fastest way to get a local environment up and running with a complete dataset.
+- **Database Restoration**: It uses the `sqlite-diffable` dump from the `_data` branch to restore the local SQLite database to the latest production state.
+- **Forced Updates**: It includes a `--force` flag to delete all local data and perform a clean sync, which is useful for resolving data inconsistencies.
+
+## Pipeline Architecture (`/src/lib/pipelines`)
+
+While the `/cli` directory provides the entry point, the core logic of the pipeline is located in `/src/lib/pipelines`. The system is designed to be modular, with each major function (`ingest`, `contributors`, `export`, `summarize`) residing in its own subdirectory.
+
+### Shared Components
+
+Several files in `/src/lib/pipelines` provide shared functionality used across the different pipeline stages:
+
+- **`runPipeline.ts`**: A higher-order function that wraps each pipeline stage. It handles common tasks like creating a pipeline context, managing verbose logging, and handling errors.
+- **`pipelineConfig.ts`**: This file is responsible for loading and validating the main `pipeline.config.ts` file from the repository root. It provides the rest of the pipeline with access to repository lists, scoring weights, and other configurations.
+- **`queryHelpers.ts`**: Contains a collection of reusable Drizzle ORM database query functions that are used by multiple pipeline stages (e.g., fetching repository IDs, getting user data).
+- **`types.ts`**: Defines the core TypeScript types and Zod schemas that are shared across all pipeline stages, ensuring data consistency.
+- **`generateTimeIntervals.ts`**: A utility for creating the `DateRange` objects used throughout the pipelines to process data for specific daily, weekly, or monthly periods.
+- **`getActiveContributors.ts` & `getSelectedRepositories.ts`**: Helper functions to determine which users and repositories should be processed based on the current configuration and command-line arguments.

docs/docs/api/data/schema/index.md

@@ -0,0 +1,44 @@
+# data/schema
+
+## Variables
+
+- [commitFilesRelations](variables/commitFilesRelations.md)
+- [commitsRelations](variables/commitsRelations.md)
+- [issueCommentReactions](variables/issueCommentReactions.md)
+- [issueComments](variables/issueComments.md)
+- [issueCommentsRelations](variables/issueCommentsRelations.md)
+- [issueLabels](variables/issueLabels.md)
+- [issueLabelsRelations](variables/issueLabelsRelations.md)
+- [issueReactions](variables/issueReactions.md)
+- [issuesRelations](variables/issuesRelations.md)
+- [labels](variables/labels.md)
+- [labelsRelations](variables/labelsRelations.md)
+- [prClosingIssueReferences](variables/prClosingIssueReferences.md)
+- [prCommentReactions](variables/prCommentReactions.md)
+- [prComments](variables/prComments.md)
+- [prCommentsRelations](variables/prCommentsRelations.md)
+- [prReactions](variables/prReactions.md)
+- [prReviews](variables/prReviews.md)
+- [prReviewsRelations](variables/prReviewsRelations.md)
+- [pullRequestFilesRelations](variables/pullRequestFilesRelations.md)
+- [pullRequestLabels](variables/pullRequestLabels.md)
+- [pullRequestLabelsRelations](variables/pullRequestLabelsRelations.md)
+- [pullRequestRelations](variables/pullRequestRelations.md)
+- [rawCommitFiles](variables/rawCommitFiles.md)
+- [rawCommits](variables/rawCommits.md)
+- [rawIssues](variables/rawIssues.md)
+- [rawPullRequestFiles](variables/rawPullRequestFiles.md)
+- [rawPullRequests](variables/rawPullRequests.md)
+- [repositories](variables/repositories.md)
+- [repoSummaries](variables/repoSummaries.md)
+- [repoSummariesRelations](variables/repoSummariesRelations.md)
+- [tags](variables/tags.md)
+- [tagsRelations](variables/tagsRelations.md)
+- [userDailyScores](variables/userDailyScores.md)
+- [userDailyScoresRelations](variables/userDailyScoresRelations.md)
+- [userDailySummariesRelations](variables/userDailySummariesRelations.md)
+- [users](variables/users.md)
+- [usersRelations](variables/usersRelations.md)
+- [userSummaries](variables/userSummaries.md)
+- [userTagScores](variables/userTagScores.md)
+- [userTagScoresRelations](variables/userTagScoresRelations.md)

docs/docs/api/data/schema/variables/commitFilesRelations.md

@@ -0,0 +1,5 @@
+# Variable: commitFilesRelations
+
+> `const` **commitFilesRelations**: `Relations`\<`"raw_commit_files"`, \{ `commit`: `One`\<`"raw_commits"`, `true`\>; \}\>
+
+Defined in: [src/lib/data/schema.ts:495](https://github.com/elizaOS/elizaos.github.io/blob/4810f50019028b92f4f2a0ac31323fd787c7f288/src/lib/data/schema.ts#L495)

docs/docs/api/data/schema/variables/commitsRelations.md

@@ -0,0 +1,5 @@
+# Variable: commitsRelations
+
+> `const` **commitsRelations**: `Relations`\<`"raw_commits"`, \{ `author`: `One`\<`"users"`, `false`\>; `files`: `Many`\<`"raw_commit_files"`\>; `pullRequest`: `One`\<`"raw_pull_requests"`, `false`\>; \}\>
+
+Defined in: [src/lib/data/schema.ts:483](https://github.com/elizaOS/elizaos.github.io/blob/4810f50019028b92f4f2a0ac31323fd787c7f288/src/lib/data/schema.ts#L483)