Terkix-dev · Huynhthuongg · Jun 7, 2026 · Jun 7, 2026 · Jun 7, 2026 · Jun 12, 2026
diff --git 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
@@ -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, cache-safe service worker routing, persistent UI preferences, and one-click workspace snapshot export.
+- **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
@@ -3,11 +3,17 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>My Google AI Studio App</title>
+    <meta name="description" content="TerKix Terminal OS: a Termux-inspired AI-native multi-agent software development workspace." />
+    <meta name="theme-color" content="#030508" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-title" content="TerKix" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <link rel="apple-touch-icon" href="/terkix-logo.svg" />
+    <link rel="icon" type="image/svg+xml" href="/terkix-logo.svg" />
+    <title>TerKix Terminal OS</title>
   </head>
   <body>
     <div id="root"></div>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
-
diff --git a/metadata.json b/metadata.json
@@ -1,6 +1,10 @@
 {
-  "name": "RKix Terminal OS",
-  "description": "AI-native terminal-based software development environment with autonomous planner, builder, designer, debugger, and deployer agents.",
-  "requestFramePermissions": [],
-  "majorCapabilities": ["MAJOR_CAPABILITY_SERVER_SIDE_GEMINI_API"]
+  "name": "TerKix Terminal OS",
+  "description": "AI-native terminal-based software development environment with autonomous planner, builder, designer, debugger, deployer, plugin, contact, and telemetry agents.",
+  "requestFramePermissions": [
+    "microphone"
+  ],
+  "majorCapabilities": [
+    "MAJOR_CAPABILITY_SERVER_SIDE_GEMINI_API"
+  ]
 }