docs: Interfaces documentation

docs/source/guide/admin-interfaces.md

@@ -0,0 +1,80 @@
+---
+title: Interface admin settings
+short: Interfaces
+tier: enterprise
+type: guide
+hide_menu: false
+order: 0
+order_enterprise: 363
+meta_title: Interface admin settings
+section: "Manage Your Organization"
+parent_enterprise: "admin_settings"
+date: 2025-02-18 12:03:59
+---
+
+
+The **Organization > Settings > Interfaces** page is where Owners and Admins turn the Interfaces feature on for the organization and configure the security `allowlist` that every Interface runs against.
+
+These settings apply uniformly to every Interface in your organization — embedded iframes, the main labeling canvas, the in-product preview, and the Develop Locally playground.
+
+Access these settings from  **Organization > Settings > Interfaces**.
+
+
+## Enable Interfaces
+
+Toggle **Allow projects in this organization to use Interfaces** to make the Interfaces feature available across the organization. 
+
+## API origins
+
+Hosts that Interfaces are allowed to reach via `fetch`, `XHR`, or `WebSocket` (the CSP `connect-src` directive). 
+
+| Rule | Detail |
+| --- | --- |
+| Format | Full origin including scheme, for example `https://api.example.com`. |
+| Wildcards | Not allowed (no `*` or `*.example.com`). List specific hosts. |
+| Empty | An empty list means **no outbound network from Interfaces** — they can only call your Label Studio server. |
+| Whitespace and commas | Rejected. Add one host per entry. |
+
+!!! info Tip
+    Your Label Studio server's own origin is always allowed automatically — you don't need to add it. Only list third-party hosts.
+
+## Iframe capabilities
+
+Capabilities that Interfaces are allowed to request through the iframe `allow=` attribute. Click any chip to toggle it on or off. The list is intentionally narrow:
+
+| Capability | Typical use |
+| --- | --- |
+| `autoplay` | Playing audio or video without user interaction. |
+| `camera` | Reading from the device camera. |
+| `clipboard-write` | Programmatically copying to the clipboard. |
+| `encrypted-media` | Playing DRM-protected media. |
+| `fullscreen` | Entering fullscreen mode. |
+| `geolocation` | Reading the user's location. |
+| `idle-detection` | Detecting when the user is idle. |
+| `language-detector` | Using the on-device language detection API. |
+| `microphone` | Reading from the device microphone. |
+| `on-device-speech-recognition` | Running speech recognition locally. |
+| `storage-access` | Requesting unpartitioned storage access. |
+
+!!! warning
+    Stay minimal. Every enabled capability is something an Interface (including a third-party or experimental one) could call into. Only enable a capability when an Interface in your organization needs it.
+
+## Advanced: external scripts
+
+Use this section to allow Interfaces to load third-party `<script>` and `<style>` tags from a list of trusted hosts.
+
+Enable **Allow external scripts / stylesheets** to unlock the origin list and then add one or more script origins, for example `https://cdn.jsdelivr.net`.
+
+| Rule | Detail |
+| --- | --- |
+| Scheme | Must be `https://`. HTTP origins are rejected. |
+| Format | Origin only — no paths, query strings, credentials, or fragments. |
+| Wildcards | Not allowed. |
+| Toggle | Origins are ignored unless the **Allow external scripts** checkbox is on. Turning the checkbox off clears the list on save. |
+
+!!! warning
+    Scripts loaded from these origins run with the Interface's full privileges and can read any task data the Interface is rendering. Only add hosts you trust completely. Most organizations should leave this section disabled.
+
+
+
+

docs/source/guide/interfaces-agent.md

@@ -0,0 +1,114 @@
+---
+title: Use the Label Studio agent to create an Interface
+short: Create with agent
+tier: enterprise
+type: guide
+order: 0
+order_enterprise: 142
+meta_title: Interfaces
+meta_description: "Build custom labeling interfaces with React"
+section: "Interfaces"
+---
+
+You can create Interfaces in two ways:
+
+* **Within Label Studio** - Use Label Studio's out-of-the-box Interface builder to prompt our agent to build and refine your Interface. 
+
+* **Developed locally** - Install the `create-interface-skill` and use an agent of your choice to vibe code an Interface that you can then import into Label Studio. For more information, see [Develop an Interface locally](interfaces-local).
+
+To begin, select **Interfaces** in the main menu and then select **Create Interface > Create with Agent**. 
+
+!!! info Tip
+    If you want to start from an existing labeling UI rather than a blank slate, select the overflow menu next to any Interface and select **Duplicate**. From here you can edit the copy. 
+
+
+![Screenshot](/images/interfaces/create-interface.png)
+
+
+
+The Interface builder is comprised of the following tabs:
+
+| Tab | Description |
+| --- | --- |
+| [**Chat**](#Chat) | Provide instructions to the Label Studio agent to build out your custom interface. |
+| [**Code**](#Code) | View and manually update the React component created during your building session. |
+| [**Version navigator**](#Version-navigator) | As you iterate on the interface via chat, you can navigate between versions of the preview. |
+| [**Preview**](#Preview) | An interactive preview of your interface. |
+| [**Input/Output**](#Input-Output) | Customize the input data you want to see in the preview, and see the output you would achieve as you interact with the preview. |
+| [**Config**](#Config) | Once you have a basic version of the Interface built, you can use this tab to modify the interface rather than iterating through the chat. |
+| [**Grid Cell**](#Grid-Cell) | If you enabled **Build custom grid view** in the settings, this tab lists each grid cell. |
+
+## Chat
+
+The **Chat** tab is where you collaborate with the agent to build the Interface.
+
+In the message box at the bottom, describe the labeling UI you want. Be specific about:
+
+- What the annotator should see (text, image, dialogue, side-by-side documents, etc.).
+- What they are being asked to do (pick a label, highlight spans, fill a form, rank options).
+- Any domain constraints (label names, required fields, rules).
+
+
+### Plan mode
+
+In Plan mode, the agent will surface:
+
+- **Question cards** — Multiple-choice questions the agent uses to narrow the design. Click the options that apply and submit.
+- **A plan summary card** — The proposed design. You can **Approve** it, **Approve with edits** (tweak the plan text first), or **Revise** (send feedback and let the agent propose again).
+
+Once the plan is approved, the agent switches to code generation.
+
+<img src="/images/interfaces/plan-mode.png" style="max-width: 500px" alt="Screenshot of Plan mode">
+
+
+### Settings
+
+You can select whether you want to build a custom grid view for your Interface.
+
+Grid view allows you add a custom summary that appears in the Data Manager when viewing tasks in Grid View. This summary can be edited when modifying the Interface from the project settings. 
+
+## Code
+
+The **Code** tab is where you can view and manually update the React component created during your building session.
+
+## Version navigator
+
+As you update the Interface, the preview will update to reflect the changes. You can move between versions of the Interface using the controls above the chat panel:
+
+<img src="/images/interfaces/versions.png" style="max-width: 500px" alt="Screenshot of Versions">
+
+Use this to:
+
+- Step through every snapshot the agent has produced and every manual edit you've made.
+- Roll the preview back to an earlier version if a later change broke something.
+- Pick any earlier snapshot as the basis for the next prompt.
+
+!!! info Tip
+    Versions you navigate to stay editable — you can keep refining from any point in history.
+
+## Preview
+
+Every time the agent writes or edits code, the **Preview** on the right re-renders using the current sample task data. Click around in the preview exactly as a labeler would — if something looks wrong, describe the fix in chat and the agent will patch the code.
+
+If the code has a syntax or runtime error, an error message appears in the preview pane so you know what's broken.
+
+!!! info Tip
+    As you interact with the preview, check the **Input/Output** tab to see a preview of the annotation output in JSON format. Ensure this matches what you would expect.  
+
+## Input/Output
+
+| Section | Description |
+| --- | --- |
+| **Input** | The input data that the Interface reads from. You can edit the example input to see how the Interface behaves against realistic data. |
+| **Output** | The output data that the Interface produces. As you interact with the interface under the **Preview** tab, this section automatically updates to show the output in JSON format. |
+
+## Config 
+
+The **Config** tab allows you to adjust the Interface's annotation controls. For example, you can add or delete choices, change the colors of labels, adjust the display text of labels, and more. The changes you make will be reflected in the preview and the code. 
+
+These values can also be updated in the **Chat** panel by describing the changes you want to make, and can also be updated later from the project settings.
+
+## Grid Cell
+
+The **Grid Cell** tab only appears if you have enabled **Build custom grid view** in the settings. It lists each grid cell in the Interface. 
+

docs/source/guide/interfaces-details.md

@@ -0,0 +1,91 @@
+---
+title: View Interface details
+short: Interface details
+tier: enterprise
+type: guide
+order: 0
+order_enterprise: 145
+meta_title: Interfaces
+meta_description: "View, manage, and version custom labeling Interfaces"
+section: "Interfaces"
+---
+
+The Interface details page is the home base for a saved Interface. Use it to inspect the Interface, edit it, manage versions, and create projects from it.
+
+To open it, select **Interfaces** in the main menu and then select the Interface you want to view.
+
+![Screenshot](/images/interfaces/details.png)
+
+## Actions
+
+The top bar of the Interface details page provides the following actions:
+
+| Button | Description |
+| --- | --- |
+| [**Iterate with Agent**](interfaces-agent) | Open the interface editor with the agent. This will open a new tab with the interface editor and the agent. |
+| [**Develop Locally**](interfaces-local) | Install the `create-interface-skill` and work with a local coding agent to develop your Interface. |
+
+
+And from the overflow menu in the top right corner of the page:
+
+| Action | Description |
+| --- | --- |
+| **Edit** | Edit the Interface name and description. |
+| **Create Project** | Starts a new project pinned to the version currently selected in the [version navigator](#Versions). For more information, see [Use an Interface in a project](./interfaces-project.md). |
+| **Duplicate** | Creates a new copy of the Interface. |
+| **Delete** | Delete the Interface. This action is not available if the Interface is used by any projects. |
+
+!!! info Tip
+    Template Interfaces can only be used and edited by duplicating them first. 
+
+## Preview
+
+The **Preview** section renders the Interface against the current sample task data, exactly as a labeler will see it. Click through the controls to confirm the Interface behaves the way you expect.
+
+!!! info Tip
+    The preview always reflects the version currently selected in the [version navigator](#Versions). Switch versions to compare how the Interface behaved at different points in its history.
+
+## Versions
+
+A list of versions appears to the right of the **Preview** section.
+
+Select a version to update the **Preview**, **Data I/O**, and **Code** sections to that version's source.
+
+You can also manage versions from the overflow menu next to that version:
+
+| Action | Description |
+| --- | --- |
+| **Add Description** | Add a description to the version. |
+| **Unpublish** | When you create projects from an Interface, project managers can switch between interface versions from the context of the project. <br /><br />Unpublishing a version will hide it from the version list under **Project > Settings > Labeling Interface.**   |
+
+<img src="/images/interfaces/version-overflow.png" style="max-width: 500px" alt="Screenshot of Version overflow menu">
+
+
+## Data I/O
+
+The **Data I/O** section provides information about the required input and the expected output of the Interface.
+
+Use this section to confirm the Interface reads the task fields you plan to import and produces the annotation shape downstream workflows (exports, analytics, Prompts) expect.
+
+!!! info Tip
+    You can edit the example task data to see how the Interface behaves against realistic data.
+
+## Projects
+
+The **Projects** section lists every project currently using this Interface, along with the version each project is pinned to, the creation date, and the task count.
+
+From this section you can:
+
+- Click a project to open it directly.
+- Click **Create Project** to start a new project from the Interface. The project is pinned to the version currently selected in the version navigator.
+
+!!! info Tip
+    Editing an Interface does not retroactively update existing projects. Each project keeps running against its pinned version until you upgrade it from the project's labeling settings. See [Use an Interface in a project](interfaces-project) for more information.
+
+## Code
+
+The **Code** section shows the read-only JSX source for the selected version. Use it to:
+
+- Audit what the Interface actually does before attaching it to a project.
+- Copy snippets to share with teammates or paste into a duplicate.
+- Confirm the Interface exposes the optional helpers you expect (such as `paramsSchema`, `outputSchema`, or `GridCell`).