# Forge AI Studio A polished, local-first browser workspace for creating, configuring, previewing, and managing custom AI assistants. ## Masterplan - Let solo builders and small teams define specialized AI assistants without requiring an account, backend, or model-provider setup. - Store agent configurations entirely in the current browser so users can experiment safely and immediately. - Make an agent’s purpose, tone, operating instructions, and reference materials visible and editable in one focused workflow. - Provide a deterministic local playground that demonstrates how an agent configuration shapes replies; it is explicitly **not** a live LLM integration. ## Tech Stack & Architecture - **React + TypeScript** entry point: `src/main.tsx`. - **Vite** build/dev environment configured in `vite.config.ts`. - **React Router DOM** with `HashRouter`; routes work on static hosting without server-side route rewrites. - **Tailwind CSS v4 Vite plugin** via `@tailwindcss/vite`, with global tokens and application styling in `src/styles/main.css`. - **lucide-react** provides all interface icons. - **clsx + tailwind-merge** are wrapped by `cn()` in `src/lib/utils.ts` for safe Tailwind class composition. ### Application composition `src/main.tsx` mounts: ```tsx ``` `src/App.tsx` establishes provider order and renders every route inside the persistent shell: ```tsx ... ``` - `AgentProvider` is the source of truth for all agent data. - `ToastProvider` supplies transient success, error, and informational notifications. - `AppShell` owns responsive navigation and in-memory theme toggling. - Page components consume context through `useAgents()` and `useToast()` rather than passing state through route props. ### Persistence and state - Agent data is stored under the browser `localStorage` key **`forge-ai-studio-agents`**. - `loadAgents()` in `src/lib/data.ts` returns `starterAgents` when storage is missing, malformed, or not an array. - `AgentContext.tsx` persists the entire current collection after every agent-state update. - Chat transcripts on `AgentDetailPage.tsx`, search text on `AgentsPage.tsx`, open modals, and theme state are session-only React state; they are not persisted. - Theme state only toggles the `dark` class on ``. It is not saved to localStorage and defaults to whatever class is already present at load time. ### No backend or external AI API There is no API server, authentication, database, file upload system, or live LLM provider. The only remote asset usage is generated agent imagery from `https://picsum.photos/...`. ## File Structure ```text index.html # Root HTML, app metadata, and #root mount node. package.json # Vite/React runtime and development dependencies. vite.config.ts # React and Tailwind Vite plugins. src/ main.tsx # Mounts App in React.StrictMode and HashRouter. App.tsx # Provider tree and all route declarations. types/ index.ts # Agent, AgentTone, ChatMessage, and ToastItem contracts. context/ AgentContext.tsx # In-memory agent CRUD, cloning, and localStorage persistence. ToastContext.tsx # Global auto-dismiss toast queue and useToast hook. lib/ data.ts # Starter agents plus localStorage load/persist helpers. utils.ts # cn() Tailwind class merger and display-date formatter. components/ AppShell.tsx # Desktop sidebar; mobile header and bottom navigation; theme toggle. AgentForm.tsx # Shared create/edit agent form, validation, and knowledge-chip editing. ui/ Button.tsx # Variant-aware, accessible button with loading treatment. Card.tsx # Standard bordered card wrapper. EmptyState.tsx # Reusable empty/not-found panel with action. Modal.tsx # Dialog with Escape, overlay close, basic focus trap, and body scroll lock. Skeleton.tsx # Generic animated placeholder. pages/ StudioPage.tsx # Dashboard/landing workspace summary and agent discovery. AgentsPage.tsx # Searchable agent-library table. NewAgentPage.tsx # New-agent screen using AgentForm. EditAgentPage.tsx # Existing-agent edit screen using AgentForm. AgentDetailPage.tsx # Agent profile, local playground, clone, and delete flow. styles/ main.css # Tailwind import/theme tokens and global visual styling. ``` ## Key Features ### Agent library and CRUD The core data model in `src/types/index.ts` is: ```ts interface Agent { id: string; name: string; description: string; initials: string; tone: 'Direct' | 'Warm' | 'Analytical' | 'Creative'; instructions: string; knowledge: string[]; status: 'Ready' | 'Draft'; updatedAt: string; conversations: number; image: string; } ``` `AgentContext.tsx` exposes: - `agents` - `addAgent(agent)` - `updateAgent(agent)` - `removeAgent(id)` - `cloneAgent(id)` Important behavior: - Newly created agents receive IDs in the form `agent-${Date.now()}`. - Initials are automatically derived from the first two initials of the supplied name. - New and edited agents are saved with `status: 'Ready'`. - New agents receive a seeded Picsum image URL, although the list/detail UI primarily uses initials avatars. - Clones are prepended to the library, named `"{Original Name} Copy"`, set to `Draft`, reset to zero conversations, and receive a timestamp-suffixed ID. - Cloning intentionally retains the source agent’s description, tone, instructions, knowledge, image, and initials. ### Agent form `src/components/AgentForm.tsx` is shared by `/agents/new` and `/agents/:id/edit`. Requirements: - Name: minimum **3** trimmed characters. - One-line purpose: minimum **12** trimmed characters. - Instructions: minimum **20** trimmed characters. - Tone is constrained to `Direct`, `Warm`, `Analytical`, or `Creative`. - Knowledge sources are plain text labels, not files. Add only non-empty, non-duplicate exact strings. - Form submission navigates to `/agents/:id` after calling `onSave`. - Preserve the existing agent’s ID, conversation count, and image on edits. Do not imply that “knowledge” entries are uploaded documents or indexed content: they are currently only strings stored in the `knowledge` array. ### Agent detail and local playground `src/pages/AgentDetailPage.tsx` displays the profile, operating instructions, tone, and knowledge shelf. The playground: - Maintains `ChatMessage[]` only in component state. - Produces a deterministic response assembled from the agent name, tone, submitted prompt, and first two sentence fragments of `agent.instructions`. - Makes no network request and does not increment `agent.conversations`. - Can clear the current in-page transcript. - Must retain the visible copy: “A deterministic browser preview, not a live model call.” ### Agent search `src/pages/AgentsPage.tsx` filters locally against the concatenated lowercase: - `agent.name` - `agent.description` - `agent.tone` Search does not include instructions, knowledge entries, status, or ID. The table is horizontally scrollable on narrow viewports (`min-w-170`). ### Feedback and destructive actions - `ToastContext.tsx` removes notifications automatically after **4200 ms**; users may dismiss them manually. - Deletion from `AgentDetailPage.tsx` requires confirmation through `Modal.tsx`. - A deleted or unknown route ID renders an `EmptyState` instead of throwing or redirecting automatically. ## Design Guidelines ### Visual language - Clean, editorial “studio/workbench” UI: warm neutral surfaces, compact rounded cards, thin borders, restrained shadows, and a purple primary accent. - Use semantic Tailwind token classes defined by `src/styles/main.css`: `bg-background`, `bg-card`, `border-border`, `text-muted-foreground`, `bg-primary`, `text-success`, `text-warning`, and `text-destructive`. - Do not hardcode replacement hex values in components when a semantic token exists. - Icons come from `lucide-react`, generally at `size-4` or `size-5`, with `aria-hidden` when paired with text. ### Typography and spacing - Existing pages use a hierarchy of small muted eyebrow labels, `text-3xl` page titles, and `text-xl`/`text-2xl` card titles. - Favor `tracking-tight` for headings and readable `text-sm leading-6` for instruction content. - Main content widths: - `max-w-7xl` for dashboard, library, and detail screens. - `max-w-3xl` for create/edit forms. ### Responsive behavior - Desktop (`lg`): fixed 256px sidebar; content receives `lg:ml-64`. - Mobile/tablet: sticky top header plus fixed bottom navigation; main content includes `pb-24` so it is not obscured. - The sidebar is intentionally hidden below `lg`; do not add duplicate navigation patterns without updating both layouts. - Modals are bottom-sheet style on mobile and centered dialogs from `sm` upward. ### Accessibility - Preserve visible focus rings (`focus-visible:ring-*`) on interactive additions. - Form fields have associated labels or `sr-only` labels. - `Modal.tsx` handles Escape, overlay click, body scroll lock, initial close-button focus, and a basic Tab focus loop. Keep its `id="forge-modal"` unique. ## App Flow 1. **Studio (`#/`)** - Default entry route inside `AppShell`. - Serves as the workspace overview and directs users into the agent library or agent creation. 2. **Browse agents (`#/agents`)** - View persisted starter agents and user-created agents in a searchable table. - Select a row or agent-name button to open its detail page. - Empty library leads to `#/agents/new`; a no-match search offers query clearing. 3. **Create (`#/agents/new`)** - Define identity, tone, instructions, and optional knowledge labels. - Invalid submissions reveal field errors; no save occurs. - Successful save is local, emits a toast, and lands on the new agent detail route. 4. **Inspect/test (`#/agents/:id`)** - Review the operating profile and knowledge shelf. - Test with local deterministic chat. - Edit, clone, or delete the agent. 5. **Edit (`#/agents/:id/edit`)** - Prepopulates `AgentForm`. - Save updates localStorage, displays a confirmation toast, and returns to detail. - Invalid/missing IDs show an empty state. 6. **Theme** - Accessible in desktop sidebar and mobile bottom navigation. - It affects the current DOM session only; page reload may reset the choice. ## Conventions - Use TypeScript types from `src/types/index.ts`; update the `Agent` interface and all creation paths together when extending agent fields. - Use default-exported React components, matching the existing files. - Keep route components in `src/pages/`, shared domain components in `src/components/`, and generic visual primitives in `src/components/ui/`. - Use `useAgents()` for agent mutations. Do not write directly to localStorage from pages or components. - Use `useToast()` for user-visible operation feedback rather than custom inline success banners. - Use `cn()` from `src/lib/utils.ts` for conditional or overrideable Tailwind class strings. - Keep data local-first unless intentionally introducing a backend. If adding real model calls, replace the deterministic playground copy and clearly model loading, errors, credentials, conversation persistence, and usage counts. - Add a page by creating `src/pages/{Feature}Page.tsx`, registering its route in `src/App.tsx`, and adding navigation in `src/components/AppShell.tsx` only if it is a primary destination. - Add a reusable agent form field or card section in `src/components/AgentForm.tsx`; preserve its create/edit compatibility and validation behavior. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.