diff --git a/README.md b/README.md
index 60fdecc..12b511a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,199 @@
 # glancr
-A Markdown documentation viewer written in Go and React.
+
+A modern Markdown documentation viewer built with Go and React. **glancr** provides a clean, fast interface for browsing and viewing Markdown documentation with live reload capabilities during development.
+
+## Features
+
+- 🚀 **Fast & Lightweight** - Single binary deployment with embedded assets
+- 📝 **Markdown Rendering** - Beautiful rendering of Markdown documents
+- 🔄 **Live Development** - Hot reload during development
+- 🎨 **Modern UI** - Clean, responsive React-based interface
+- 📱 **Mobile Friendly** - Responsive design that works on all devices
+- 🔧 **Easy Setup** - Simple development and deployment workflow
+
+## Prerequisites
+
+- **Go** 1.19+ 
+- **Node.js** 18+ and npm
+- **Git**
+
+## Quick Start
+
+### Development
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/smjklake/glancr.git
+   cd glancr
+   ```
+
+2. **Install dependencies**
+   ```bash
+   make deps
+   ```
+
+3. **Start development servers**
+   ```bash
+   make dev
+   ```
+
+   This will start:
+   - Frontend dev server at http://localhost:5173
+   - Backend API server at http://localhost:8080
+
+### Production Build
+
+1. **Build for production**
+   ```bash
+   make build-prod
+   ```
+
+2. **Run the binary**
+   ```bash
+   ./dist/glancr
+   ```
+
+   The application will be available at http://localhost:8080
+
+## Available Commands
+
+### Development
+- `make dev` - Start development environment with live reload
+- `make build-dev` - Build development version (filesystem assets)
+- `make test` - Run Go tests
+
+### Production  
+- `make build-prod` - Build production version (embedded assets)
+- `make release` - Clean build for production release
+- `make build-cross-prod` - Build for multiple platforms
+
+### Utilities
+- `make clean` - Clean build artifacts
+- `make clean-all` - Deep clean including node_modules
+- `make deps` - Install all dependencies
+- `make help` - Show all available commands
+
+## Project Structure
+
+```
+glancr/
+├── cmd/
+│   └── server/          # Application entry point
+│       └── main.go
+├── internal/            # Private application code
+│   ├── auth/           # Authentication logic
+│   └── fs/             # Asset handling (dev/prod)
+├── ui/                 # React frontend
+│   ├── src/
+│   ├── public/
+│   └── package.json
+├── dist/               # Build output
+├── Makefile           # Build automation
+├── dev.sh             # Development script
+└── go.mod             # Go module definition
+```
+
+## Architecture
+
+**glancr** uses a clean architecture with clear separation between frontend and backend:
+
+- **Backend (Go)**: Serves the React SPA and provides API endpoints
+- **Frontend (React)**: Modern TypeScript-based UI with Vite tooling
+- **Asset Handling**: Development mode serves from filesystem, production embeds assets in binary
+- **Build System**: Makefile orchestrates both Go and Node.js build processes
+
+## Development Workflow
+
+### Adding Features
+
+1. **Backend changes**: Add logic in `internal/` packages
+2. **Frontend changes**: Modify React components in `ui/src/`
+3. **API endpoints**: Update server routes in `cmd/server/main.go`
+
+### Testing
+
+```bash
+# Run Go tests
+make test
+
+# Run with production build tags
+make test-prod
+
+# Run all tests
+make test-all
+```
+
+### Code Quality
+
+The frontend includes:
+- **ESLint** for code linting
+- **Prettier** for code formatting  
+- **TypeScript** for type safety
+
+```bash
+cd ui
+npm run lint          # Check for linting issues
+npm run lint:fix      # Fix auto-fixable issues
+npm run format        # Format code with Prettier
+```
+
+## Deployment
+
+### Single Binary Deployment
+
+Build and deploy the production binary:
+
+```bash
+make release
+scp dist/glancr user@server:/path/to/deployment/
+```
+
+### Cross-Platform Builds
+
+Generate binaries for multiple platforms:
+
+```bash
+make build-cross-prod
+```
+
+Produces:
+- `glancr-linux-amd64`
+- `glancr-darwin-amd64` 
+- `glancr-darwin-arm64`
+- `glancr-windows-amd64.exe`
+
+## Configuration
+
+Currently **glancr** runs with minimal configuration. The server starts on port 8080 by default.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests (`make test`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+### Development Guidelines
+
+- Follow Go conventions and use `gofmt`
+- Write tests for new functionality
+- Use TypeScript for frontend development
+- Run `make lint` before committing
+- Keep commits atomic and well-described
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [Go](https://golang.org/) and [React](https://reactjs.org/)
+- Bundled with [Vite](https://vitejs.dev/)
+- Styled with modern CSS practices
+
+---
+
+**glancr** - Making documentation beautiful, one markdown file at a time. ✨
\ No newline at end of file
diff --git a/internal/fs/fs_dev.go b/internal/fs/fs_dev.go
index e25abc8..e260524 100644
--- a/internal/fs/fs_dev.go
+++ b/internal/fs/fs_dev.go
@@ -8,5 +8,5 @@ import (
 )
 
 func getUIAssets() fs.FS {
-	return os.DirFS("internal/fs/dist")
+	return os.DirFS("ui/dist")
 }
diff --git a/ui/README.md b/ui/README.md
index da98444..6e42fee 100644
--- a/ui/README.md
+++ b/ui/README.md
@@ -1,54 +1,251 @@
-# React + TypeScript + Vite
+# glancr UI
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+The React frontend for **glancr** - a modern Markdown documentation viewer. This UI provides a clean, responsive interface built with React 19, TypeScript, and Vite.
 
-Currently, two official plugins are available:
+## Tech Stack
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- **React 19** - Latest React with concurrent features
+- **TypeScript** - Type-safe JavaScript development
+- **Vite** - Fast build tool and dev server
+- **ESLint** - Code linting and quality checks
+- **Prettier** - Code formatting
+- **CSS3** - Modern styling with CSS custom properties
 
-## Expanding the ESLint configuration
+## Prerequisites
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+- **Node.js** 18+ 
+- **npm** (comes with Node.js)
 
-```js
-export default tseslint.config({
-  extends: [
-    // Remove ...tseslint.configs.recommended and replace with this
-    ...tseslint.configs.recommendedTypeChecked,
-    // Alternatively, use this for stricter rules
-    ...tseslint.configs.strictTypeChecked,
-    // Optionally, add this for stylistic rules
-    ...tseslint.configs.stylisticTypeChecked,
-  ],
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
+## Quick Start
+
+### Development
+
+1. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Start development server**
+   ```bash
+   npm run dev
+   ```
+   
+   The UI will be available at http://localhost:5173
+
+3. **Start with backend** (recommended)
+   ```bash
+   npm run dev:full
+   ```
+   
+   This starts both the Vite dev server and the Go backend server.
+
+### Production Build
+
+```bash
+npm run build
+```
+
+Outputs optimized files to `dist/` directory.
+
+## Available Scripts
+
+### Development
+- `npm run dev` - Start Vite dev server only
+- `npm run dev:full` - Start both frontend and backend servers
+- `npm run watch` - Build in watch mode
+
+### Building
+- `npm run build` - Production build
+- `npm run preview` - Preview production build locally
+
+### Code Quality
+- `npm run lint` - Run ESLint checks
+- `npm run lint:fix` - Fix auto-fixable ESLint issues
+- `npm run format` - Format code with Prettier
+- `npm run format:check` - Check if code is properly formatted
+
+## Project Structure
+
+```
+ui/
+├── src/
+│   ├── assets/         # Static assets (images, icons, etc.)
+│   ├── App.tsx         # Main application component
+│   ├── App.css         # Application styles
+│   ├── main.tsx        # Application entry point
+│   ├── index.css       # Global styles
+│   └── vite-env.d.ts   # Vite type definitions
+├── public/             # Public static files
+├── dist/               # Build output (generated)
+├── index.html          # HTML template
+├── package.json        # Dependencies and scripts
+├── vite.config.ts      # Vite configuration
+├── tsconfig.json       # TypeScript configuration
+├── tsconfig.app.json   # App-specific TypeScript config
+├── tsconfig.node.json  # Node-specific TypeScript config
+├── eslint.config.ts    # ESLint configuration
+└── prettier.config.ts  # Prettier configuration
+```
+
+## Development Guidelines
+
+### Code Style
+
+- **TypeScript**: Use strict type checking
+- **Components**: Functional components with hooks
+- **Naming**: PascalCase for components, camelCase for functions/variables
+- **Imports**: Use absolute imports when possible
+
+### File Organization
+
+As the project grows, consider this structure:
+
+```
+src/
+├── components/         # Reusable UI components
+│   ├── common/        # Generic components
+│   └── markdown/      # Markdown-specific components
+├── hooks/             # Custom React hooks
+├── types/             # TypeScript type definitions
+├── utils/             # Utility functions
+├── styles/            # CSS modules or styled components
+└── api/               # API client functions
+```
+
+### Component Guidelines
+
+- Use TypeScript interfaces for prop types
+- Implement proper error boundaries
+- Follow React best practices for hooks
+- Use semantic HTML elements
+- Ensure accessibility (ARIA labels, keyboard navigation)
+
+Example component structure:
+```typescript
+interface MyComponentProps {
+  title: string;
+  onAction?: () => void;
+}
+
+export function MyComponent({ title, onAction }: MyComponentProps) {
+  // Component logic here
+  return (
+    <div>
+      <h2>{title}</h2>
+      {/* Component JSX */}
+    </div>
+  );
+}
+```
+
+## API Integration
+
+The frontend communicates with the Go backend through a proxy configuration in `vite.config.ts`:
+
+```typescript
+server: {
+  proxy: {
+    '/api': {
+      target: 'http://localhost:8080',
+      changeOrigin: true,
     },
   },
-})
+}
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+This allows you to make API calls to `/api/*` endpoints during development, which will be proxied to the Go server.
 
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+## Environment Variables
 
-export default tseslint.config({
-  plugins: {
-    // Add the react-x and react-dom plugins
-    'react-x': reactX,
-    'react-dom': reactDom,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended typescript rules
-    ...reactX.configs['recommended-typescript'].rules,
-    ...reactDom.configs.recommended.rules,
-  },
-})
+Create a `.env.local` file for local environment variables:
+
+```env
+VITE_API_BASE_URL=http://localhost:8080
 ```
+
+Access in code:
+```typescript
+const apiUrl = import.meta.env.VITE_API_BASE_URL;
+```
+
+## Testing
+
+Currently, no testing framework is configured. Consider adding:
+
+- **Vitest** - Fast unit testing (Vite-native)
+- **Testing Library** - React component testing
+- **Playwright** - End-to-end testing
+
+## Performance Considerations
+
+- **Code Splitting**: Use React.lazy() for route-based splitting
+- **Bundle Analysis**: Use `npm run build` and analyze bundle size
+- **Images**: Optimize images and use appropriate formats
+- **Caching**: Leverage Vite's built-in caching strategies
+
+## Deployment
+
+The UI is built and embedded into the Go binary for production. The build process:
+
+1. `npm run build` creates optimized files in `dist/`
+2. The Go build process embeds these files using `//go:embed`
+3. The resulting binary serves the UI as a SPA
+
+## Browser Support
+
+- **Modern browsers** with ES2020+ support
+- **Chrome/Edge** 88+
+- **Firefox** 84+
+- **Safari** 14+
+
+## Troubleshooting
+
+### Common Issues
+
+**Port already in use**
+```bash
+# Kill process using port 5173
+lsof -ti:5173 | xargs kill -9
+```
+
+**Node modules issues**
+```bash
+# Clean install
+rm -rf node_modules package-lock.json
+npm install
+```
+
+**TypeScript errors**
+```bash
+# Check TypeScript configuration
+npx tsc --noEmit
+```
+
+### Development Tips
+
+- Use React DevTools browser extension
+- Enable Vite's built-in HMR for instant updates
+- Use TypeScript strict mode for better type safety
+- Set up your editor with ESLint and Prettier extensions
+
+## Contributing
+
+When contributing to the UI:
+
+1. Follow the established code style
+2. Add TypeScript types for new components
+3. Test your changes in both dev and production builds
+4. Run linting and formatting before committing
+5. Consider responsive design for all screen sizes
+
+## Integration with Backend
+
+The UI is designed to work seamlessly with the Go backend:
+
+- **Development**: Vite proxy handles API routing
+- **Production**: Served as static files by Go server
+- **SPA Routing**: Backend handles client-side routing fallback
+
+---
+
+Part of the **glancr** project - making documentation beautiful, one component at a time. ⚛️
\ No newline at end of file