docs: expand README with prerequisites, testing guide, and Kollavarsham month reference

README.md

@@ -1,12 +1,65 @@
-# Alexa Malayalam Calendar
+# Alexa Malayalam Calendar Skill
 
-## Testing
+An Alexa skill that calculates and announces today's date in the Malayalam Kollavarsham calendar along with the corresponding Nakshatra (birth star), calculated in real-time according to Indian Standard Time (IST).
 
+---
+
+## Development Prerequisites & Tools
+
+To build, test, and deploy this project, ensure you have the following tools installed on your environment:
+
+### 1. Node.js & npm
+- **Node.js**: Version 20.x or higher (Supports Node.js 24+).
+- **npm**: Version 10.x or higher.
+- **Type Support**: Uses native ES Modules (`"type": "module"` with `.mjs` files).
+
+Verify your setup:
+
+```powershell
+node -v
+npm -v
 ```
-    node test/test-local.mjs
+
-    or
+### 2. PowerShell
-    npm test
+- Required by the build and deployment scripts (`./scripts/build.ps1` and `./scripts/deploy.ps1`).
-```
+- Included by default on **Windows 10 / 11**.
+- On **macOS / Linux**, install PowerShell Core (`brew install --cask powershell`).
+
+### 3. AWS CLI (Optional — for Deployment)
+- Required if you plan to deploy the compiled Lambda handler directly using the deploy script.
+- Install from the Official AWS CLI Page.
+- Configure credentials with sufficient IAM permissions before running deployment: `aws configure`
+
+## Getting Started
+
+### 1. Installation
+Clone the repository and install the development dependencies:
+
+1. `git clone <your-repository-url>`
+2. `cd MalayalamCalendarAlexaSkill`
+3. `npm install`
+
+## Development & Testing
+
+The project uses `ask-sdk-test` for end-to-end intent tests for Alexa request envelopes,
+and Mocha to provide isolated unit testing for core calendar math. 
+
+### Run All Tests
+- `npm test`
+
+### Run Specific Test Suites
+- Unit test for date conversion & Kollavarsham calculations: `npx mocha tests/calendar.spec.mjs`
+- Integration test for Alexa launch and intent handlers: `npx mocha tests/index.spec.mjs`
+
+## Build & Deployment
+
+### Build Deployment Package
+Packages `src/` and production `node_modules` into a zip bundle suitable for AWS Lambda upload:
+- `npm run build`
+
+### Deploy to AWS Lambda
+Executes the PowerShell deploy script to upload the latest artifact to your configured AWS Lambda function:
+- `npm run deploy`
 
 ## Info
 
@@ -32,6 +85,6 @@ In Kerala, the Amanta system is followed.
 - 11 Mithunam (മിഥുനം), Jun – Jul, Heavy rains
 - 12 Karkidakam (കർക്കടകം), Jul – Aug, Ramayana Masam, Ayurveda Season
 
-## Reference for Comparison
+### Reference Calendar for Verification
 
 https://www.drikpanchang.com/malayalam