docs: improve setup documentation and add .env.sample template

.dev.vars.sample

@@ -0,0 +1,17 @@
+# Alpha One Labs Education Platform - Environment Variables Template
+# Copy this file to `.dev.vars` for local development.
+# Do not commit real secrets to version control.
+
+# ========================================
+# Encryption
+# ========================================
+# Used to encrypt user PII (Personal Identifiable Information) and activity data
+# before storing it in the database. Ensure this is a strong randomly generated string.
+ENCRYPTION_KEY=your-dev-encryption-key-here
+
+# ========================================
+# Authentication
+# ========================================
+# Used to sign JSON Web Tokens (JWT) for stateless user authentication.
+# Keep this secret to prevent unauthorized token forging.
+JWT_SECRET=your-dev-jwt-secret-here

.gitignore

@@ -17,6 +17,7 @@ venv/
 .env
 .env.local
 .dev.vars
+!.dev.vars.sample
 
 # OS
 .DS_Store
@@ -27,3 +28,4 @@ Thumbs.db
 .idea/
 *.swp
 .env*
+!.dev.vars.sample

README.md

@@ -14,102 +14,113 @@ Alpha One Labs is an education platform designed to facilitate both learning and
 
 ### Prerequisites
 
-Make sure you have installed:
- - Node.js
- - Wrangler CLI
+Before starting, ensure you have the following installed:
+ - **Node.js**: v18.0.0 or higher
+ - **npm**: v9.0.0 or higher
+ - **Wrangler CLI**: For deploying Cloudflare Workers
 
-Install Wrangler:
+Install Wrangler globally using npm:
 
 ```bash
 npm install -g wrangler
 ```
 
-### Clone the Repository
+### Fork & Clone the Repository (For Contributors)
+
+If you are a contributor, first fork the repository to your own GitHub account.
 
 ```bash
-git clone https://github.com/alphaonelabs/learn.git
+# Clone your fork (replace <your-username> with your actual username)
+git clone https://github.com/<your-username>/learn.git
 cd learn
+
+# Add the original repository as an upstream remote
+git remote add upstream https://github.com/alphaonelabs/learn.git
 ```
 
 ### Login to Cloudflare (One time)
 
+Authenticate the Wrangler CLI with your Cloudflare account. This will open a browser window to complete the login process safely.
+
 ```bash
 wrangler login
 ```
 
 ### Setup Database (D1)
 
-- Create Database:
+Follow these step-by-step instructions to set up your Cloudflare D1 database:
+
+1. **Create the Database:**
 
 ```bash
 wrangler d1 create education_db
 ```
 
-- Add the generated database_id to your wrangler.toml:
+2. **Add configuration to `wrangler.toml`:**
+   After running the create command, copy the `database_id` from the output and update your `wrangler.toml` file with this placeholder:
 
 ```toml
 [[d1_databases]]
 binding = "DB"
 database_name = "education_db"
-database_id = "YOUR_DATABASE_ID"
+database_id = "<YOUR_DATABASE_ID>"
 ```
 
-- Apply Schema:
+3. **Apply the Schema:**
+   Run the following to set up your database tables (for local development):
 
 ```bash
-wrangler d1 execute education_db --file=schema.sql
+wrangler d1 execute education_db --local --file=schema.sql
 ```
 
 ### Setup Environment Variables
 
 This project requires environment variables for encryption and authentication.
 
-- For Local Development
+#### For Local Development
 
-Create a `.dev.vars` file in the project root:
+Copy `.dev.vars.sample` to `.dev.vars` in the project root, then replace the placeholder values with your own secrets.
 
 ```
 ENCRYPTION_KEY=your-dev-encryption-key
 JWT_SECRET=your-dev-jwt-secret
 ```
 
-- For Production
-Use Wrangler secrets:
+#### For Production
+
+Use the Wrangler CLI to set secrets securely for your deployed worker:
 
 ```bash
 wrangler secret put ENCRYPTION_KEY
 wrangler secret put JWT_SECRET
 ```
 
+### Running the Application
 
-### Run Backend
+The application consists of a backend worker and frontend HTML files. Run them concurrently in separate instructions.
 
-```bash
-wrangler dev
-```
+#### Run Backend
 
-Backend server starts at:
+Start the Cloudflare Worker locally:
 
 ```bash
-http://127.0.0.1:8787
+wrangler dev
 ```
 
-### Run Frontend
+The backend server usually starts at: `http://127.0.0.1:8787`
 
-- Open directly
+#### Run Frontend
 
-```bash
-public/index.html
-```
-
-- Use a local server
+Serve the static files using a local development server (like `serve`):
 
 ```bash
 npx serve public
 ```
 
-Frontend Server will start at:
+The frontend server usually starts at: `http://localhost:3000`
 
-```bash
-http://localhost:3000
-```
+### Common Errors
+
+- **`wrangler: command not found`**: Ensure that npm's global bin directory is in your system's PATH.
+- **`D1_ERROR` when running backend**: Check that you have replaced `<YOUR_DATABASE_ID>` with your actual database ID inside `wrangler.toml`.
+- **CORS Errors**: If the frontend cannot communicate with the backend, ensure your backend is running (`wrangler dev`) and check the console. Ensure you are accessing the frontend via a local server (e.g., `http://localhost:3000`) rather than a `file://` URL.