From 5070d1c1a0a27d4304e87d457342e7a748fd0f41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hu=E1=BB=B3nh=20Th=C6=B0=C6=A1ng?=
<252359928+Huynhthuongg@users.noreply.github.com>
Date: Sun, 7 Jun 2026 18:22:24 +0700
Subject: [PATCH 1/4] Restore TerKix branding and UI flow
---
.env.example | 15 ++-
README.md | 95 ++++++++++++++
index.html | 5 +-
metadata.json | 12 +-
package-lock.json | 188 +++++++++++++++++++++++++--
package.json | 20 +--
public/terkix-logo.svg | 30 +++++
server.ts | 160 +++++++++++++++--------
src/App.tsx | 153 +++++++++++++---------
src/components/ContactsManager.tsx | 6 +-
src/components/DashboardOverview.tsx | 28 ++--
src/components/PluginManager.tsx | 10 +-
src/components/TelemetryD3Chart.tsx | 2 +-
src/data/presets.ts | 6 +-
src/utils/storage.ts | 85 ++++++++++++
vite.config.ts | 2 +-
16 files changed, 650 insertions(+), 167 deletions(-)
create mode 100644 public/terkix-logo.svg
create mode 100644 src/utils/storage.ts
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..5abec67 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,95 @@
+# 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.
+- **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
+```
+
+## 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..dcb5567 100644
--- a/index.html
+++ b/index.html
@@ -3,11 +3,12 @@
- My Google AI Studio App
+
+
+ TerKix Terminal OS