docs: review readme files

.cursor/rules/README.md

@@ -0,0 +1,74 @@
+# Development Rules
+
+This directory contains development standards and best practices for different aspects of the codebase. These rules are used by the AI assistant to help maintain consistency and quality across the project.
+
+## Available Rules
+
+### Frontend Development
+
+- **[nextjs.mdc](./nextjs.mdc)**: Next.js development standards and patterns
+- **[react-hooks.mdc](./react-hooks.mdc)**: React hooks patterns and best practices
+- **[tailwind.mdc](./tailwind.mdc)**: Tailwind CSS and UI component guidelines
+- **[typescript.mdc](./typescript.mdc)**: TypeScript coding standards and best practices
+- **[web-vitals-perf.mdc](./web-vitals-perf.mdc)**: Web Vitals and performance optimization guidelines
+
+### Web3 Integration
+
+- **[viem.mdc](./viem.mdc)**: Viem v2 integration patterns and best practices
+- **[wagmi.mdc](./wagmi.mdc)**: Web3 integration patterns using Wagmi v2
+- **[solidity.mdc](./solidity.mdc)**: Solidity development standards with Foundry
+
+### Data Layer
+
+- **[ponder.mdc](./ponder.mdc)**: Ponder indexing standards and best practices
+
+## Usage
+
+These rules are automatically applied when:
+
+1. Files matching the rule's glob pattern are opened
+2. The AI assistant is asked to help with code related to a specific technology
+3. Code reviews are performed by the AI assistant
+
+## Rule Format
+
+Each rule file follows this format:
+
+```markdown
+---
+description: Brief description of the rule's purpose
+globs: "**/*.{extension}" # File patterns this rule applies to
+---
+
+# Title
+
+## Section 1
+Guidelines and examples...
+
+## Section 2
+More specific rules...
+```
+
+## Contributing
+
+When adding new rule files or updating existing rules:
+
+1. Follow the established concise format
+2. Include clear examples and explanations
+3. Define appropriate glob patterns
+4. Add the rule file or update the rule entry in this README
+5. Ensure consistency with existing rules
+6. Review and test the new or updated rules to ensure they work as expected
+
+## Maintenance
+
+Rules should be regularly reviewed and updated to:
+
+- Keep up with latest best practices
+- Incorporate team feedback
+- Address common issues
+- Align with project evolution
+
+## License
+
+MIT License

.cursor/rules/ponder.mdc

@@ -5,6 +5,11 @@ globs: "**/ponder/**/*.ts"
 
 # Ponder Best Practices
 
+- Define clear indexing strategies for your use case
+- Implement efficient event handlers
+- Use Ponder's GraphQL API for querying indexed data
+- Optimize indexing performance with proper database indexing
+
 ## Database Operations
 
 ### Reading Data

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to BasilicEVM
+# Contributing 
 
-Thank you for your interest in contributing to BasilicEVM! This document outlines our contribution guidelines and development workflow.
+Thank you for your interest in contributing! This document outlines our contribution guidelines and development workflow.
 
 ## Code Standards & Rules
 

README.md

@@ -8,17 +8,20 @@ A performance-optimized development stack for EVM applications. Built with Found
 - __Chain Integration__: viem/wagmi, Alchemy RPC
 - __Frontend__: Next.js 15, React Server Components
 - __Data Layer__: Ponder indexing, Supabase
+- 
 ## Project Structure
 
 ### Apps
 - [__apps/web__](./apps/web/README.md) - Next.js frontend
 - [__apps/ponder__](./apps/ponder/README.md) - Chain indexing service
 
 ### Packages
+- [__packages/ui__](./packages/ui/README.md) - Shadcn/ui and custom components
 - [__packages/core__](./packages/core/README.md) - Chain interactions, contract ABIs
 - [__packages/react__](./packages/react/README.md) - Web3 React hooks
 - [__packages/supabase__](./packages/supabase/README.md) - Database/auth integration
 - [__packages/lib__](./packages/lib/README.md) - Shared utilities
+- [__packages/tsconfig__](./packages/tsconfig/README.md) - TypeScript configuration
 
 ## Development Setup
 

apps/ponder/README.md

@@ -1,8 +1,9 @@
-# BasilicEVM Ponder Service
+# Ponder
 
 ## Overview
 
-BasilicEVM Ponder indexes blockchain events, transforms data, and exposes it via a GraphQL + RPC API. Integrated with Supabase for database lifecycle management and deployment.
+Ponder indexes blockchain events, transforms data, and exposes it via a GraphQL + RPC API. Integrated with Supabase for database lifecycle management and deployment.
+For detailed usage instructions please refer to the [BACKEND.md](../../BACKEND.md) documentation.
 
 ## Features
 

apps/web/README.md

@@ -1,15 +1,17 @@
-# BasilicEVM Webapp
+# Web
 
 ## Overview
 
-The BasilicEVM webapp is built with Next.js 14 and follows a performance-optimized architecture for EVM applications. It's part of a larger monorepo that includes smart contracts (Foundry), indexing services (Ponder), and shared packages.
+The web app is built with Next.js 15 and follows a performance-optimized architecture for EVM applications. 
 
 ## Core Features
 
 - URL-based state management
 - API for reading and subscribing to data
 - EVM transaction push for writing
 - Code organization by route and feature
+- Next.js 15's new Turbopack for faster builds
+- React Server Components for improved performance
 
 ## Architectural Principles
 

apps/web/components/layout/providers.tsx

@@ -13,7 +13,7 @@ const queryClient = new QueryClient()
 export const wagmiConfig = createConfig({
   chains: [arbitrumSepolia],
   transports: {
-    [arbitrumSepolia.id]: http(webConfig.services.rpc.arbitrumSepolia)
+    [arbitrumSepolia.id]: http(webConfig.services.rpc.arbitrumSepolia),
   },
 })
 

packages/core/README.md

@@ -1,4 +1,4 @@
-# @repo/core Package
+# @repo/core package
 
 Core package for interacting smart contracts.
 

packages/lib/README.md

@@ -1,4 +1,4 @@
-# @repo/lib Package
+# @repo/lib package
 
 This package contains shared utilities, functions, constants, and configuration files that can be used across multiple projects in the monorepo.
 

packages/next/README.md

@@ -1,4 +1,4 @@
-# @repo/next Package
+# @repo/next package
 
 This package contains utilities and helpers for Next.js applications.
 

packages/react/README.md

@@ -1,4 +1,4 @@
-# @repo/react Package
+# @repo/react package
 
 A TypeScript package that provides React hooks for interacting with smart contracts using Wagmi v2 and Viem v2.
 

packages/supabase/README.md

@@ -1,6 +1,7 @@
-# @repo/supabase
+# @repo/supabase package
 
-Supabase module that handles database interactions.
+This module provides comprehensive tools for managing database interactions using Supabase.
+For detailed usage instructions please refer to the [BACKEND.md](../../BACKEND.md) documentation.
 
 ## Features
 

packages/tsconfig/README.md

@@ -1,4 +1,4 @@
-# @repo/tsconfig
+# @repo/tsconfig package
 
 This package contains shared TypeScript configurations used across the monorepo.
 

packages/ui/README.md

@@ -0,0 +1,60 @@
+# @repo/ui package
+
+A TypeScript package that provides reusable UI components and utilities built with Tailwind CSS and shadcn/ui.
+
+## Features
+
+- Modern, accessible UI components
+- Built with Tailwind CSS and Radix UI primitives
+- Fully customizable with consistent design tokens
+- Type-safe component props with TypeScript
+- Responsive and mobile-first design
+- Dark mode support out of the box
+
+## Installation
+
+```bash
+pnpm install @repo/ui
+```
+
+## Usage
+
+```typescript
+import { Button } from '@repo/ui'
+
+function MyComponent() {
+  return (
+    <Button variant="primary">
+      Click me
+    </Button>
+  )
+}
+```
+
+## Best Practices
+
+- Use semantic HTML elements for better accessibility
+- Follow mobile-first responsive design principles
+- Maintain consistent spacing and typography using design tokens
+- Ensure proper ARIA attributes for interactive components
+- Test components across different viewports and themes
+- Document component props and usage examples
+
+## Components
+
+The package hosts the following components:
+
+- Button variants (primary, secondary, ghost)
+- Form controls (input, select, checkbox)
+- Layout components (container, grid, stack)
+- Navigation elements (menu, tabs, breadcrumbs)
+- Feedback indicators (alert, toast, progress)
+- Data display (card, table, list)
+
+## Contributing
+
+Please refer to the root [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## License
+
+MIT License