# HostKeeper | Developer & AI System Brief

> **MANDATORY INSTRUCTION FOR DOWNSTREAM AI AGENTS:**
> Before proposing or implementing any changes, code edits, or new features in this workspace, you **MUST** read this instruction set fully. Every visual and architectural decision must align strictly with the rules defined below.

---

## 1. Visual Identity & Design System (Lumina System)

Unlike standard, heavy, dark-themed hacker dashboards, HostKeeper uses the **Lumina System**—a premium, "bright-tech" glassmorphic developer workspace featuring clean off-whites, slate cards, vibrant accent highlights, and a high-clarity layout.

### A. Color Palette
Maintain the exact CSS variables and color definitions declared in `/src/index.css`:
*   **Primary (Lumina Blue):** `#0050cb` (Focus boundaries, active selections, primary indicators)
*   **Secondary (Neon Green):** `#006e2f` (Active/Online indicators, progress bars, successful transactions)
*   **Tertiary (Tech Purple):** `#7e23cc` (File directories, custom command responses, highlight badges)
*   **Surface Base Background:** `#f7f9fb`
*   **Containers & Cards Lowest:** `#ffffff` (High-contrast pure white cards for depth separation)
*   **Text/On-Surface Dark Slate:** `#191c1e` (Main UI text)
*   **Subtle Labels/On-Surface Variant:** `#424656`

### B. Grid, Depth & Glassmorphic Accents
*   **Dot Grid Texture:** The background uses a responsive 16px repeating radial dot pattern:
    `radial-gradient(#e2e8f0 1.5px, transparent 1.5px)` with a size of `16px 16px`.
*   **Frosted Glass Sidebars & Overlays:** Use `backdrop-blur-md` and semi-transparent white backgrounds (`rgba(255, 255, 255, 0.7)`) to show subtle grid depth underneath overlays.
*   **Elevation & Shadows:** Focus containers should never have heavy dark borders. Instead, apply thin borders (`border-outline-variant/30`) paired with subtle, color-matched glow shadows (`shadow-primary/10`).

### C. Typography Pairing
*   **Interface UI Font:** **Inter** (weights `300` to `900`). Used for titles, descriptive labels, tables, navigation buttons, and settings forms.
*   **Technical / Data Font:** **JetBrains Mono** (weights `300` to `700`). Used exclusively for file paths, IP addresses, terminal prompt commands, and cataloged snippet blocks.

---

## 2. File & Component Architecture

Keep the project highly modular. Do not merge separate view components into a single file to avoid hitting token limit cutoffs.

*   `/src/types.ts`: Holds shared global interfaces (e.g., `Host`, `FileItem`, `Snippet`, `KeychainItem`, `Device`, `BackgroundTransfer`).
*   `/src/App.tsx`: The primary state router. Houses active navigation, sidebar frames, quick-action overlays, and global mock state stores.
*   `/src/components/DashboardView.tsx`: Hosts list, connection triggers, and background file-transfer progress bars.
*   `/src/components/SftpView.tsx`: Dual-pane local-to-remote secure file transmission and folder generation lists.
*   `/src/components/TerminalView.tsx`: Interactive multi-tab mock SSH shell supporting customized terminal parser actions.
*   `/src/components/SnippetsView.tsx`: DevOps script store with full search index, copy utility, and custom snippet registration.
*   `/src/components/KeychainView.tsx`: Secure local keystore sandbox with passphrase disclosure controls, strength validators, and SHA256 fingerprints.
*   `/src/components/SettingsView.tsx`: Profile configuration forms, feature toggle switches, and local storage state resets.
*   `/src/components/BriefOverlay.tsx`: In-app system documentation and layout specifications viewer.

---

## 3. Core Functional & Interaction Guidelines

When expanding HostKeeper features, future agents must adhere to the following implementation behaviors:

1.  **Icon Guidelines:**
    *   All icons **MUST** be imported strictly from `lucide-react`.
    *   Do **NOT** write custom inline SVGs.
2.  **Terminal Simulation Parser:**
    *   Inside `TerminalView.tsx`, the interactive shell handles input commands.
    *   Always extend the mock commands list (`help`, `ls`, `docker ps`, `uname -a`, `ping 8.8.8.8`, `cat server.js`, `keychain`, `clear`) rather than falling back to blank prompts.
3.  **Real-time SFTP Actions:**
    *   SFTP View simulates file transmission. Clicking a file or the upload/download button triggers path transfers with real-time UI feedback. Keep the interactive toast banners operational.
4.  **No Unsolicited SDKs or Servers:**
    *   Keep the app fully client-side and snappy unless requested otherwise.
    *   Avoid creating unnecessary external backends or adding database service modules unless explicitly specified.

---

## 4. Development Verification Steps

Before finishing any task, run these commands sequentially to guarantee app integrity:

1.  **Check Linter Rules:**
    `npm run lint` or call the `lint_applet` tool to identify imports or compilation issues early.
2.  **Verify Production Build Compilation:**
    `npm run build` or call the `compile_applet` tool to ensure TypeScript checks and asset optimization pass without errors.