docs: update readme + fix paper url

Author: kevinjosethomas

README.md

@@ -1,188 +1,132 @@
-# maia platform
+<div align="center" style="margin-bottom: 3rem;">
+  <img src="public/maia-no-bg.png" width="64" alt="Maia Chess Logo">
+  <h1><a href="https://www.maiachess.com">Maia Chess</a></h1>
+  <i>A human-like chess engine</i>
+</div>
 
-This is the code that powers the[ Maia Chess platform](https://www.maiachess.com).
-   
-It is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with the additions of [`typescript`](https://www.typescriptlang.org/), [`eslint`](https://eslint.org/), [`storybook`](https://storybook.js.org/), [`prettier`](https://prettier.io/), [`sass`](https://sass-lang.com/), [`testing-library`](https://testing-library.com/) ,and [`jest`](https://jestjs.io/).
+This repository contains the source code for the [Maia Chess Platform](https://www.maiachess.com), a modern web application designed for chess training and analysis. It leverages the Maia chess engine, developed by the University of Toronto's Computational Social Science Lab, to provide human-like move predictions and insights. The platform is built with Next.js, TypeScript, and Tailwind CSS.
 
-Initialize a new `next-app` with this project as a template by running
+Join our Discord server for discussions, questions, and to connect with the community:
+[Maia Chess Community on Discord](https://discord.gg/hHb6gqFpxZ)
 
-```bash
-npx create next-app --example https://github.com/datadeque/next-app
-# or
-yarn create next-app --example https://github.com/datadeque/next-app
-```
-
-## Development Guide
-
-This project uses [`yarn`](https://yarnpkg.com/) and is developed & maintained for [`node`](https://nodejs.org/en/) version 17+ (however CI will try builds using versions 12, 14, and 16 as well).
-
-The recommended code editor is [`vscode`](https://code.visualstudio.com/) along with the following extensions (see `.vscode/extensions.json`):
-
-- eslint (Linter)
-- prettier (Formatter)
-- mdx (Syntax Highlighting for Storybook)
+## Getting Started
 
-These extensions are highly recommended along with vscode because the project is pre-configured to format and fix ALL fixable issues on save. Furthermore, please open this project by running `code .` in the root directory from your terminal since there are known issues with environment variables when opening the project from gui.
+Follow these instructions to set up the development environment on your local machine.
 
-It also helps to know the following tools:
+### Prerequisites
 
-- [`sass`](https://sass-lang.com/)
-- [`react contexts`](https://reactjs.org/docs/context.html)
-- [`react custom hooks`](https://reactjs.org/docs/hooks-custom.html)
+- Node.js (v17+ recommended)
+- npm (comes bundled with Node.js)
 
-### Design
+### Installation
 
-Each page of the platform can be found in `src/pages`. Inside, a wrapper component fetches the data from the api and renders the page itself when the data is received. An example of this is in the `train` page where `TrainPage` fetches the game, and renders `Train`.
+1.  Clone the repository to your local machine:
 
-We'll refer the component rendered by the wrapper as the main component. Inside the main component a custom hook is used to isolate all the logic, and two variables `mobileLayout` and `desktopLayout` are initialized to represent the corresponding layouts.
+    ```bash
+    git clone https://github.com/maia-chess/maia-platform-frontend.git
+    cd maia-platform-frontend
+    ```
 
-The `GameControllerContext` is used to simply pass data down, as any child component of the main component can easily consume the controller without passing it down multiple layers using props.
+2.  Install the project dependencies using npm:
+    ```bash
+    npm install
+    ```
 
-Each main component typically contains a `GameBoard` component which renders the lichess chessboard UI, and a family of surrounding components that are either interactive or show information such as analysis.
+### Running the Development Server
 
-### Getting Started
-
-First, install the dependencies by running
+To start the local development server, run the following command. This will launch the application on `http://localhost:3000` with hot-reloading enabled.
 
 ```bash
-yarn
-# or
-yarn install
+npm run dev
 ```
 
-Then start the development server by running
+### Building for Production
+
+To create a production-ready build of the application, use the following command. This will compile and optimize the code, outputting the final assets to the `.next` directory.
 
 ```bash
-yarn dev
+npm run build
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+You can then start the production server with `npm run start`.
 
-You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
+## Development Guide
 
-### Storybook
+This section provides guidelines for contributing to the platform's development.
 
-To start storybook development server by running
+### Branching Strategy
 
-```bash
-yarn storybook
-```
+The repository follows a simple branching model:
 
-Open http://localhost:6006/ with your browser and see the result.
+- `main`: This branch is synced with the live deployment on Vercel. All code on this branch is considered production-ready.
+- **Feature Branches**: All development work, including new features and bug fixes, should be done on separate feature branches. These branches are then merged into `main` via pull requests.
 
-### Linting & Testing
+### Conventional Commits
 
-You can lint the entire project using the built-in `eslint` config by running
+We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for our commit messages. This standard creates a more readable and structured commit history. Each commit message should follow the format:
 
-```bash
-yarn lint
-```
+`{type}: {description}`
 
-This is the same command that runs during the lint step of the initial CI.
+Common types include:
 
-You can run your test files by running
+- `feat`: A new feature
+- `fix`: A bug fix
+- `chore`: Changes to the build process or auxiliary tools
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `docs`: Documentation only changes
 
-```bash
-yarn test
-```
+### Architectural Overview
 
-This is the same command that runs during the test step of the initial CI.
+The platform is architected around a modular and scalable structure, leveraging modern React patterns.
 
-## Development Practices
+#### File Structure
 
-### Committing
+The `src/` directory contains all the core application code, organized as follows:
+
+```
+src/
+├── api/          # Backend API client functions, organized by feature
+├── components/   # Reusable React components, structured by feature or domain
+├── contexts/     # React Context providers for global state management
+├── hooks/        # Custom React Hooks containing business logic and state
+├── pages/        # Next.js pages, defining the application's routes
+├── providers/    # Wrappers for context providers
+├── styles/       # Global styles and Tailwind CSS configuration
+├── types/        # TypeScript type definitions, organized by feature
+└── utils/        # Utility functions and helpers
+```
 
-Conventional commits is a pretty simple convention, you can learm more about it [here](https://www.conventionalcommits.org/en/v1.0.0/).
+#### Core Concepts and Interactions
 
-Basically commit messages follow the following format: `{action}: {description}`, where action is one of `feat`, `chore`, `fix`, `style`... and description is description of the change in present tense.
+The application's logic is primarily driven by a combination of custom hooks, React contexts, and components, creating a clear separation of concerns.
 
-### Testing
+- **Components (`src/components/`)**: These are the building blocks of the UI. They are designed to be "dumb" or presentational, receiving data and callbacks via props. Major features like `Analysis`, `Play`, `Openings`, and `Training` have their own dedicated component directories.
 
-Every react component should atleast have one test, to see if it renders. Test files are to be placed in `__test__` and follow the same file structure as the project root.
+- **Hooks (`src/hooks/`)**: This is where the majority of the application's business logic resides. Each major feature has a corresponding "controller" hook (e.g., `usePlayController`, `useAnalysisController`). These hooks encapsulate state management, interactions with the chess engines, and API calls. They effectively act as state machines for their respective features.
 
-Suppose you built a new component under `src/components/button/button.tsx`, a test should be placed in `__tests__/components/button/button.test.tsx` with the following:
+- **Contexts (`src/contexts/`)**: To avoid prop drilling, we use React Context to provide the state and methods from our controller hooks to the component tree. For example, `PlayControllerContext` will expose the state and functions from the `usePlayController` hook to any child component that needs it, such as the `GameBoard` or `PlayControls`.
 
-```tsx
-import { render } from '@testing-library/react'
-import Button from 'components/button'
+This architecture allows for a decoupled system where the UI (components) is a function of the state managed by the hooks, and the state is shared efficiently through contexts. For example, a page component under `src/pages` will initialize a controller hook. That hook's state is then provided to the component tree via a Context Provider. Child components can then consume that context to access state and dispatch actions without passing props down multiple levels.
 
-describe('Button', () => {
-  it('renders', () => {
-    render(<Button />)
-  })
-})
-```
+#### Learning Resources
 
-This will ensure that future modifications by others won't severely break your component. Should you have a complex component that interacts with its props, you should add some more complex tests.
+To better understand the patterns used in this codebase, we recommend reviewing the official documentation for these core React and Next.js features:
 
-### File Structure
+- [React Hooks](https://react.dev/reference/react/hooks)
+- [React Context](https://react.dev/reference/react/createContext)
+- [Next.js App Router](https://nextjs.org/docs)
 
-Below is the an example of a recommended file structure:
+### Client-Side Chess Engines
 
-```
-src/
-    pages/
-    components/
-        ComponentName/
-            ComponentName.tsx
-            index.tsx
-            styles.scss # Modular Styles if needed
-        index.tsx
-    styles/
-    contexts/
-    hooks/
-    utils/
-```
+A key feature of the platform is its ability to run both Stockfish and Maia directly in the user's browser. This is accomplished using WebAssembly and ONNX Runtime Web.
 
-## Github Actions
-
-This project is has the following pre-configuration, which tests, lints and builds all branches and PRs.
-
-```yaml
-name: CI
-
-on:
-  push:
-  pull_request:
-    branches: ['**']
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-      - run: yarn
-      - run: yarn test
-
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-      - run: yarn
-      - run: yarn lint
-
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node: ['12', '14', '16', '17']
-    name: Node ${{ matrix.node }} Build
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-        with:
-          node-version: ${{ matrix.node }}
-      - run: yarn
-      - run: yarn build
-```
+- **Stockfish (`src/hooks/useStockfishEngine/`)**: We use a WebAssembly (WASM) version of Stockfish for standard chess analysis. The `useStockfishEngine` hook provides a simple interface to interact with the engine, allowing for move evaluation streams. This provides the "objective" best moves in any given position.
 
-## Learn More
+- **Maia (`src/hooks/useMaiaEngine/`)**: The Maia engine is a neural network provided as an ONNX (Open Neural Network Exchange) model. We use the `onnxruntime-web` library to load and run Maia models on the client-side. The `useMaiaEngine` hook manages the download, initialization, and execution of the various Maia models (e.g., `maia_kdd_1100` to `maia_kdd_1900`). This engine provides the "human-like" move predictions that are central to the platform's mission.
 
-To learn more about Next.js, take a look at the following resources:
+These hooks are consumed by higher-level controller hooks (like `useAnalysisController`) to provide the dual-engine analysis that powers many of the platform's features.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Deployment
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+The Maia Chess Platform is deployed on [Vercel](https://vercel.com/). The `main` branch is automatically built and deployed to the production URL. Pull requests also generate unique preview deployments, allowing for easy testing and review before merging.

src/components/Home/AboutMaia.tsx

@@ -101,7 +101,7 @@ const researchPapers = {
     {
       title:
         'Detecting Individual Decision‑Making Style: Exploring Behavioral Stylometry in Chess',
-      link: 'https://www.cs.toronto.edu/~ashton/pubs/maia-personalized2021.pdf',
+      link: 'https://www.cs.toronto.edu/~ashton/pubs/chessembed-neurips2021.pdf',
       description:
         'Shows that your chess style is as unique as a fingerprint, allowing the model to recognize you just by your move choices.',
     },