# LiveFolio

> The Sharing, Versioning, and Feedback Layer for AI-Generated interactive HTML documents.

LiveFolio hosts, versions, and collects visual feedback on AI-generated responsive HTML documents (folios). Any AI agent, coding assistant, or chatbot can connect to LiveFolio via the Model Context Protocol (MCP) or the `auth.md` agent-authentication protocol to publish pages and retrieve reviewer feedback.

## Developer & Agent Integration

This file provides a machine-readable directory for LLMs and autonomous agents to understand how to interface with LiveFolio.

### 🤖 Model Context Protocol (MCP)
LiveFolio runs a standard MCP server at:
* Cloud/SaaS: `https://livefolio.com/api/mcp`
* Local/OSS: `http://localhost:3000/api/mcp`

### 🔑 Autoclose Authentication (`auth.md`)
LiveFolio implements the open `auth.md` protocol for agent-native registration. Agents can autonomously register workspaces and acquire API keys on behalf of users.
* Metadata & Discovery: `/.well-known/oauth-protected-resource`
* Protocol Guide: `/auth.md`

---

## Available MCP Tools

Agents equipped with the LiveFolio MCP server can call the following tools:

### `list_projects`
* **Purpose:** List all active folios in the workspace.
* **Arguments:** None.
* **Returns:** Array of project summaries including: `project_id`, `title`, `file_count`, `version_count`, `open_comments`, `share_url`, `studio_url`.

### `get_project`
* **Purpose:** Fetch full file sources, open comments, and version history of a specific project.
* **Arguments:** 
  * `project_id` (string, required): The ID of the target project.
* **Returns:** Full details including file dictionary (`index.html`, etc.), chat history, and visual comment coordinates.

### `create_project`
* **Purpose:** Create and host a new responsive folio with initial content.
* **Arguments:**
  * `title` (string, required): The name of the folio.
  * `initial_html` (string, required): The raw HTML/CSS/JS source code of `index.html`.
  * `description` (string, optional): A brief summary of the folio.
  * `project_mode` (string, optional): Intent mode matching psychology (`deck`, `document`, `spreadsheet`, `dashboard`).
  * `design_preferences` (object, optional): Theme, typography, palette presets.
* **Returns:** JSON object containing `success`, `project_id`, `share_url`, and `studio_url`.

### `update_project`
* **Purpose:** Patch or replace files in an existing project and commit a new named version checkpoint.
* **Arguments:**
  * `project_id` (string, required): Target project ID.
  * `updated_files` (object, required): A key-value map of file paths to full string content, e.g., `{ "index.html": "..." }`.
  * `change_message` (string, required): Commit summary describing what changed in this revision.
* **Returns:** JSON indicating success and new version identifier.

### `get_curated_brief`
* **Purpose:** Compile all open visual comments and annotations into a structured markdown design brief.
* **Arguments:**
  * `project_id` (string, required): Target project ID.
* **Returns:** Markdown layout mapping user pinpoint notes, DOM selectors, coordinates, and screenshots.

---

## Agent Guidelines & Design System

When generating or editing HTML pages for LiveFolio, agents MUST adhere to these unified styling guidelines:
1. **Design System:** Prioritize premium visual aesthetics: dark mode toggles, harmonious color palettes, fluid glassmorphism, responsive grids, and Google Fonts (like Outfit, Plus Jakarta Sans, Inter).
2. **Local CSS Control:** Use clean, vanilla CSS or Tailwind via CDN.
3. **No Placeholders:** Ensure all assets are complete. Generate inline SVG/Canvas code or mock content if assets are missing.
4. **Interactive States:** Leverage micro-interactions, hover effects, and CSS transitions to make the document feel active.