docs: move the documentation to FrontLit

frontlit/docs/_sections.json

@@ -1,4 +1,40 @@
 {
   "version": 1,
-  "sections": []
+  "sections": [
+    {
+      "folder": "introduction",
+      "name": "Introduction",
+      "order": 10
+    },
+    {
+      "folder": "for-agents",
+      "name": "For agents",
+      "order": 20
+    },
+    {
+      "folder": "for-apps",
+      "name": "For apps",
+      "order": 30
+    },
+    {
+      "folder": "for-humans",
+      "name": "For humans",
+      "order": 40
+    },
+    {
+      "folder": "self-hosting",
+      "name": "Self-hosting",
+      "order": 50
+    },
+    {
+      "folder": "resources",
+      "name": "Resources",
+      "order": 60
+    },
+    {
+      "folder": "upgrades",
+      "name": "Upgrades",
+      "order": 70
+    }
+  ]
 }

frontlit/docs/for-agents/cli.md

@@ -0,0 +1,122 @@
+---
+title: "CLI"
+description: "Upload and manage files from the terminal, yourself or through a coding agent."
+slug: cli
+nav_order: 20
+---
+
+The MediaLit CLI works for you in a terminal and for coding agents that run commands, such as Claude Code, Codex and Cursor's agent. It logs in with your browser, like the [MCP server](/docs/mcp-server), and works with medialit.cloud and self-hosted servers.
+
+<CodeGroup>
+
+```bash title="npm"
+npm install -g @medialit/cli
+```
+
+```bash title="pnpm"
+pnpm add -g @medialit/cli
+```
+
+```bash title="yarn"
+yarn global add @medialit/cli
+```
+
+```bash title="bun"
+bun add -g @medialit/cli
+```
+
+</CodeGroup>
+
+## Log in
+
+```bash
+medialit login
+```
+
+Your browser opens to sign in. If you have more than one app, you choose the app the CLI works with. Run `medialit login` again to choose a different one.
+
+<Tabs items={["medialit.cloud", "Self-hosted"]}>
+<Tab value="medialit.cloud">
+
+```bash
+medialit login
+```
+
+</Tab>
+<Tab value="Self-hosted">
+
+```bash
+medialit login --endpoint https://medialit.example.com
+```
+
+Later commands use the server you last logged in to. You can be logged in to several servers and pick one with `--endpoint`.
+
+</Tab>
+</Tabs>
+
+On a machine without a browser, add `--no-browser` and open the printed URL in a browser that can reach the machine's `127.0.0.1`, for example through an SSH tunnel.
+
+## Upload files
+
+```bash
+medialit upload photo.jpg --public
+```
+
+The CLI prints each file's URL. Uploads are private unless you pass `--public`.
+
+Unlike the API and the MCP server, the CLI [seals](/docs/concepts#temporary-uploads-and-sealing) each upload right away, because running the command is the decision to keep the file. Pass `--temp` to leave uploads temporary, so MediaLit deletes them after 24 hours unless you run `medialit seal <id>`. Agents should use `--temp` for scratch files.
+
+Large files are sent in chunks and retried if the connection drops.
+
+<TypeTable
+type={{
+    "--public": { type: "flag", description: "Anyone with the link can open the file." },
+    "--caption <text>": { type: "string", description: "Stored with every file in this upload." },
+    "--group <name>": { type: "string", description: "Puts the files in a group." },
+    "--temp": { type: "flag", description: "Don't seal the files." },
+  }}
+/>
+
+## Manage files
+
+```bash
+medialit ls                    # newest first, 20 at a time
+medialit ls --public --page 2
+medialit ls --group invoices
+medialit get <id>              # prints the URL, a fresh one for private files
+medialit seal <id>
+medialit rm <id>
+medialit whoami                # server, account, app and storage used
+medialit logout
+```
+
+## Use it from a coding agent
+
+Log in once yourself with `medialit login`. A coding agent running on the same machine can then run `medialit` like any other command, so you can ask it things like:
+
+> Take a screenshot of the new settings page, upload it to MediaLit as a public file and add the link to the pull request description.
+
+Tell the agent to add `--json` when it needs to read the result, for example the `mediaId` to delete the file later, and `--temp` for files it may not keep.
+
+**CLI or MCP?** Use the [MCP server](/docs/mcp-server) for assistants that can't run commands, such as Claude or ChatGPT in the browser. Use the CLI for agents that can, especially for larger files: MCP uploads are limited to about 1.5 MB, while the CLI uploads files of any size your plan allows, in resumable chunks.
+
+## Use it in scripts
+
+Every command takes `--json`. URLs and JSON go to standard output and messages to standard error, so you can pipe the result:
+
+```bash
+url=$(medialit upload build/report.pdf --public)
+medialit ls --json | jq '.[].mediaId'
+```
+
+In CI, where nobody can open a browser, set an API key instead of logging in:
+
+```bash
+export MEDIALIT_API_KEY=your_api_key
+export MEDIALIT_ENDPOINT=https://medialit.example.com # only if you self-host
+medialit upload dist/app.zip
+```
+
+## Where your login is stored
+
+In `~/.config/medialit/credentials.json`, or `%APPDATA%\medialit` on Windows. Only your user can read it. Set `MEDIALIT_CONFIG_DIR` to use another folder. `medialit logout` revokes the login on the server and removes it from the file.

frontlit/docs/for-agents/mcp-server.md

@@ -0,0 +1,215 @@
+---
+title: "MCP Server"
+description: "Control MediaLit using the Model Context Protocol (MCP)"
+slug: mcp-server
+nav_order: 10
+---
+
+## Introduction
+
+Agents create files: reports, images, exports and screenshots. The MediaLit MCP server gives any MCP client a place to keep them and a link to share. Files an agent keeps appear in your [dashboard](/docs/dashboard) and are available to your apps through the API.
+
+Once connected, you can ask things like:
+
+- "Upload this chart as a public file and give me the link."
+- "List the files I uploaded this week."
+- "Delete the drafts you made earlier."
+- "How much storage am I using?"
+
+Uploads from agents are [temporary until sealed](#two-step-upload-flow-drafts-sealing), so an agent's scratch files are cleaned up unless it, or you, decides to keep them. The [CLI](/docs/cli) is different: it seals uploads right away unless the agent passes `--temp`.
+
+The server is at `https://api.medialit.cloud/mcp` and uses the Streamable HTTP transport, so there is nothing to install or run locally.
+
+---
+
+## How to Connect
+
+MediaLit supports two ways to authenticate your MCP client. **Using the OAuth 2.0 setup is recommended** as it is the easiest and most secure option.
+
+### 1. OAuth 2.0 Setup (Recommended)
+
+Connecting with OAuth is straightforward:
+
+1. **Enter the Connection URL:** Provide the client with the MediaLit MCP server URL: `https://api.medialit.cloud/mcp`
+2. **Redirect & Login:** The client will redirect you to the MediaLit login screen.
+3. **Authorize:** Enter your email address to log in, and authorize the connection.
+
+Once approved, you are logged in and the client will automatically handle connection keys in the background.
+
+MediaLit supports Client ID Metadata Documents (CIMD) for current MCP clients and keeps Dynamic Client Registration (DCR) enabled for compatible clients. Registration identifies the client; users still sign in and approve access before it receives a token.
+
+<Callout type="info" title="Choosing an app">
+  If you have more than one app, MediaLit asks which one to connect after you sign in. The agent's uploads and changes all happen in that app. Connect again to choose a different one. The [CLI](/docs/cli) uses the same sign-in.
+</Callout>
+
+**Claude Code:**
+
+```bash
+claude mcp add --transport http medialit https://api.medialit.cloud/mcp
+```
+
+Then run `/mcp` in Claude Code to sign in.
+
+### 2. API Key Setup (Alternative)
+
+If you are using developer-focused tools like Cursor or Claude Code and prefer a quick configuration, you can use your MediaLit account API key instead.
+
+Add the following config to your client:
+
+- **Header:** `x-medialit-apikey`
+- **Value:** `YOUR_API_KEY`
+
+**Claude Desktop Configuration (`claude_desktop_config.json`):**
+
+Since Claude Desktop communicates via standard input/output (stdio), you must use a proxy/bridge tool like `mcp-remote` to connect to the remote Streamable HTTP server:
+
+```json
+{
+    "mcpServers": {
+        "medialit": {
+            "command": "npx",
+            "args": [
+                "mcp-remote",
+                "https://api.medialit.cloud/mcp",
+                "--header",
+                "x-medialit-apikey: ${API_KEY}"
+            ],
+            "env": {
+                "API_KEY": "YOUR_API_KEY"
+            }
+        }
+    }
+}
+```
+
+**VS Code configuration (`mcp.json`):**
+
+```
+{
+    "servers": {
+        "medialit": {
+            "type": "http",
+            "url": "https://api.medialit.cloud/mcp",
+            "headers": {
+                "x-medialit-apikey": "YOUR_API_KEY"
+            }
+        }
+    }
+}
+```
+
+---
+
+## Two-Step Upload Flow (Drafts & Sealing)
+
+To prevent cluttering of the media registry with unfinished uploads, MediaLit enforces a **two-step upload pattern** across both REST and MCP interfaces:
+
+1. **Upload (`upload_media`):** The file is written to storage, and a record is created with `temp: true`. In this temporary state, the file does **not** appear in paginated listings (`list_media`), count queries (`get_media_count`), or storage totals (`get_total_storage`).
+2. **Seal (`seal_media`):** The client verifies the upload and seals it. Sealing removes the `temp` flag, finalizing the record and making it globally visible to listing tools.
+
+<Callout type="warning" title="Orphan Cleanup">
+  Files left in the `temp: true` state for more than 24 hours are automatically purged by a background cleanup worker. Always ensure you call `seal_media` once the upload is completed successfully.
+</Callout>
+
+---
+
+## Tools Reference
+
+The MediaLit MCP server exposes the following tools to connected agents:
+
+### Media Management
+
+#### `list_media`
+
+Returns a paginated list of finalized (sealed) media items.
+
+- **Inputs:**
+    - `page` _(number, optional)_: Page offset (default: `1`).
+    - `limit` _(number, optional)_: Items per page (default: `10`).
+    - `access` _("public" | "private", optional)_: Filter by accessibility level.
+    - `group` _(string, optional)_: Filter by custom group label.
+- **Output:** `{ mediaItems: Array, total: number, page: number }`
+
+#### `get_media`
+
+Fetches complete metadata for a single media item by its ID.
+
+- **Inputs:**
+    - `mediaId` _(string, required)_: The unique ID of the media item.
+- **Output:** The media document.
+- **Note:** Unlike `list_media`, this tool can fetch `temp: true` (unsealed) media items, allowing validation before sealing.
+
+#### `get_media_count`
+
+Returns the total count of finalized media items in the account.
+
+- **Output:** `{ count: number }`
+
+#### `get_total_storage`
+
+Returns the total storage space consumed by the account, along with the allowed maximum limit in bytes.
+
+- **Output:** `{ storage: number, maxStorage: number }`
+
+#### `seal_media`
+
+Finalizes a temporary media upload, allowing it to persist and show up in lists/tallies.
+
+- **Inputs:**
+    - `mediaId` _(string, required)_: The unique ID of the media item to seal.
+- **Output:** The updated media document.
+
+#### `delete_media`
+
+Permanently deletes a media file and all generated derivatives (thumbnails, WebP conversions) from storage.
+
+- **Inputs:**
+    - `mediaId` _(string, required)_: The unique ID of the media item to delete.
+- **Output:** `{ deleted: true, mediaId: string }`
+
+---
+
+### File Uploading & Access
+
+#### `upload_media`
+
+Uploads a new file directly using base64-encoded payload parameters.
+
+- **Inputs:**
+    - `fileBase64` _(string, required)_: Base64-encoded string of the file bytes.
+    - `fileName` _(string, required)_: Filename with extension (e.g. `image.png`).
+    - `mimeType` _(string, required)_: The MIME type of the file (e.g. `image/png`).
+    - `caption` _(string, optional)_: Text description or caption.
+    - `access` _("public" | "private", optional)_: Access controls (default: `private`).
+    - `group` _(string, optional)_: Custom folder/group tag.
+- **Output:** `{ mediaId: string }`
+- **Limits:** Requests to the MCP server are limited to 2 MB, and base64 makes a file about a third larger, so this tool works for files up to about 1.5 MB. For larger files, an agent that can run commands can use the [CLI](/docs/cli), which uploads in resumable chunks. Otherwise, use `create_upload_signature` and upload the file with [`@medialit/uploader`](/docs/other-frameworks) or the REST API.
+
+#### `create_upload_signature`
+
+Creates a short-lived [upload signature](/docs/concepts#upload-signatures) that lets a browser or script upload one file to MediaLit without an API key.
+
+- **Inputs:**
+    - `group` _(string, optional)_: Optional group to associate with the uploaded file.
+- **Output:** `{ signature: string }`
+
+---
+
+### Media Settings
+
+#### `get_media_settings`
+
+Retrieves the active image processing configurations for the account, such as auto-conversion behaviors.
+
+- **Output:** Active configurations (WebP defaults, thumbnail dimensions).
+
+#### `update_media_settings`
+
+Overwrites specific image processing defaults. Supply only the properties you wish to modify.
+
+- **Inputs:**
+    - `useWebP` _(boolean, optional)_: Auto-convert uploaded images to WebP.
+    - `webpOutputQuality` _(number, optional)_: Output quality between `0` and `100`.
+    - `thumbnailWidth` _(number, optional)_: Default width of generated thumbnails.
+    - `thumbnailHeight` _(number, optional)_: Default height of generated thumbnails.
+- **Output:** `{ updated: true }`