CHAPTER 01

System Overview & Mission

GnamiAI (gnamiai.live) is a browser-first, cloud-hosted artificial intelligence agent runtime environment. It is architected to outperform native desktop vibe-coding applications by pairing a lightweight native Windows desktop client with isolated WebContainers execution, non-destructive virtual rollbacks, long-term memory, and multi-modal developer agency.

Four Foundational Development Principles:

• Minimal, Targeted Edits: Surgical diff modifications. Never perform wide codebase refactors or rewrite entire files when a minimal AST diff achieves the goal.
• Human-in-the-Loop (HITL) Safety: Explicit confirmation before executing potentially destructive terminal commands or schema alterations.
• Time-Machine Rollbacks: Commit micro-snapshots to a virtual branch before any agent file rewrite so you can rewind instant regressions with one click.
• Sandboxed Browser Runtime: Leverage isolated execution so code runs securely without endangering your host environment.

CHAPTER 02

Windows Native Client (.exe)

While the API, authentication, and PayPal billing reside on Cloudflare Workers, the core coding client runs as a native Windows x64 executable. This hybrid architecture grants full host file system read/write access and local terminal execution while leveraging Cloudflare edge speed for account state and model routing.

PowerShell Desktop Installation

# Download and run the native Windows installer
curl.exe -L -o GnamiAI.Installer.exe https://gnamiai.live/downloads/GnamiAI.Installer.exe
./GnamiAI.Installer.exe

CHAPTER 03

Workspace Operational Modes

GnamiAI features a fluid top-level mode switcher with three distinct runtime contexts:

1. Autopilot (Agent Mode)

Full autonomous orchestration. The agent plans out complex multi-step workflows, manages context across the entire repository, automatically runs terminal tasks, creates files, and runs verification checks with Human-in-the-Loop (HITL) approval gates.

2. Forge (Code Mode)

A high-precision developer workbench focused on targeted file editing, multi-file side-by-side Git diffs, syntax-highlighted Monaco editor workspaces, and direct terminal inspection.

3. Stream (Thread Mode)

A focused conversational and brainstorming environment for high-level architecture discussions, rapid prototyping ideas, debugging logs, and requirement drafting before touching any code.

CHAPTER 04

Time-Machine Git & Rewinds

Located directly above the code editor workbench, the Time-Machine Git timeline records micro-commits to an in-memory virtual branch prior to any mutating agent action. Regressions are rolled back with 1-click sub-second latency.

Micro-Commit Snapshot Structure

interface MicroCommit {
  id: string;
  hash: string;
  message: string;
  timestamp: number;
  author: 'agent' | 'user' | 'system';
  files: { [filePath: string]: string };
}

// Instant rollback handler
function rollbackToCommit(commitId: string): void {
  const target = virtualBranch.get(commitId);
  workspace.restore(target.files);
}

CHAPTER 05

Human-in-the-Loop (HITL) Safety

Whenever an autonomous agent requests permission to execute terminal commands or overwrite critical schema files, an interruptive modal appears. In accordance with strict black-and-white design rules:

Approve Action

Solid white button with black text. Commits a micro-snapshot and executes the task.

Reject / Modify

Transparent button with thin border. Halts execution and returns control.

CHAPTER 06

Safe Model Access Matrix (BYOS/BYOK)

GnamiAI strictly adheres to vendor Terms of Service and data privacy policies:

BYOS (Bring Your Own AI Subscription) — Safe OAuth 2.0 PKCE

Allowed exclusively for providers that explicitly support subscription bridging (such as OpenAI Codex / ChatGPT Plus). Redirects to the official provider login with PKCE verification and intercepts authorization codes without scraping web session tokens.

BYOK (Bring Your Own Key) — Strict Direct Vault

Anthropic (Claude) and Google (Antigravity/Gemini) are strictly restricted to direct API keys stored in client-side AES-GCM 256-bit encrypted storage. The UI proactively blocks unauthorized OAuth proxy attempts.

CHAPTER 08

Cloudflare Edge & Login Rate Limiter

All website assets and API routes are deployed behind Cloudflare Workers. Authentication endpoints are safeguarded by a Cloudflare Edge Rate Limiter enforcing 5 requests per 60 seconds per IP, preventing brute-force attacks and credential stuffing.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1773574060
Content-Type: application/json

{
  "error": "Too Many Requests",
  "message": "Cloudflare Login Rate Limiter: Too many login attempts. Please try again in 60 seconds.",
  "retryAfter": 60
}

CHAPTER 09

PayPal Subscriptions & Billing API

PayPal is the exclusive payment processor for recurring billing of GnamiAI Pro ($29/month). Subscriptions automatically provision 12,500 monthly compute credits, cloud sandbox quotas, and dedicated VPC routing. Runs through your own model subscriptions (Codex, Grok, etc.) never consume credits — credits apply to cloud sandbox compute only. Cloud runs are metered per action (10 credits to plan, 10 per execution, 5 per repair pass, 10 per summary), capped at 50 credits per run and 20 runs per user per day with a 120-second maximum runtime. Brief chit-chat bills a 2-credit reply instead of a full run. Your workspace files sync into the sandbox for the run, and changed files can be applied back locally with one click.