diff --git a/.env.example b/.env.example
index 7a550fe..4267a2f 100644
--- a/.env.example
+++ b/.env.example
@@ -1,9 +1,14 @@
-# GEMINI_API_KEY: Required for Gemini AI API calls.
-# AI Studio automatically injects this at runtime from user secrets.
-# Users configure this via the Secrets panel in the AI Studio UI.
+# GEMINI_API_KEY: Required for live Gemini AI API calls.
+# AI Studio can inject this at runtime from user secrets.
GEMINI_API_KEY="MY_GEMINI_API_KEY"
+# GEMINI_MODEL: Optional model override for the TerKix command endpoint.
+# Defaults to gemini-2.5-flash when omitted.
+GEMINI_MODEL="gemini-2.5-flash"
+
+# PORT: Optional local/server port.
+PORT="3000"
+
# APP_URL: The URL where this applet is hosted.
-# AI Studio automatically injects this at runtime with the Cloud Run service URL.
-# Used for self-referential links, OAuth callbacks, and API endpoints.
+# AI Studio can inject this at runtime with the Cloud Run service URL.
APP_URL="MY_APP_URL"
diff --git a/README.md b/README.md
index e69de29..347e841 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,98 @@
+# TerKix Terminal OS
+
+TerKix Terminal OS is a Termux-inspired, AI-native development workspace built with React, Vite, Express, and the Google Gemini API. It keeps the TerKix brand front-and-center while providing a terminal-first interface for managing virtual projects, files, agent workflows, deployments, plugins, contacts, and telemetry dashboards.
+
+## What this repo contains
+
+- **React 19 SPA** for the TerKix terminal, workspace explorer, dashboard, plugin hub, contacts manager, and telemetry views.
+- **TerKix logo asset** at `public/terkix-logo.svg` for the favicon, nav rail, cockpit header, and dashboard hero.
+- **Installable PWA shell** via `public/manifest.webmanifest` and `public/sw.js` for app-like launch and offline shell caching.
+- **Terminal productivity upgrades** including persisted command history, arrow-key recall, online/offline status, and cache-safe service worker routing.
+- **Express + Vite server** for local development and production static hosting.
+- **Gemini command API** at `/api/gemini/command` for multi-agent workflow generation with an offline simulator fallback in the UI.
+- **Safe local persistence** for projects, terminal history, active workspace, and command metrics.
+
+## Requirements
+
+- Node.js 22 or newer is recommended.
+- npm 10 or newer.
+- A Gemini API key when you want live AI responses. Without a configured key, the client falls back to the built-in simulator.
+
+## Environment setup
+
+Copy the example environment file and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+Supported variables:
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `GEMINI_API_KEY` | Yes for live AI | _none_ | API key used by `@google/genai`. |
+| `GEMINI_MODEL` | No | `gemini-2.5-flash` | Model used by the server command endpoint. |
+| `PORT` | No | `3000` | Port for the Express/Vite server. |
+| `APP_URL` | No | _none_ | Public URL used by hosted environments. |
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run the app locally:
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:3000`.
+
+## Quality checks
+
+Run TypeScript validation:
+
+```bash
+npm run typecheck
+```
+
+Run the full production build:
+
+```bash
+npm run build
+```
+
+Start the production build:
+
+```bash
+npm start
+```
+
+Check server health when the app is running:
+
+```bash
+curl http://localhost:3000/api/health
+```
+
+## Project structure
+
+```text
+.
+├── server.ts # Express server and Gemini command endpoint
+├── src/App.tsx # Main TerKix UI shell and workspace logic
+├── src/components/ # Dashboard, project, plugin, contact, and chart modules
+├── src/data/presets.ts # Default virtual projects and sample workspace files
+├── src/types.ts # Shared domain types
+├── src/utils/storage.ts # Defensive localStorage helpers
+└── public/ # TerKix logo, web manifest, and service worker
+```
+
+## Notes for contributors
+
+- Keep generated workspace file paths under `workspace/project/...` so the TerKix virtual file explorer can mount them correctly.
+- Keep dependencies that are only needed for builds or tooling in `devDependencies`.
+- Do not commit `.env` files or real API keys.
+- Run `npm run typecheck` and `npm run build` before opening a pull request.
diff --git a/index.html b/index.html
index 21dfe69..2912561 100644
--- a/index.html
+++ b/index.html
@@ -3,11 +3,17 @@
- My Google AI Studio App
+
+
+
+
+
+
+
+ TerKix Terminal OS