Document workload-declared UI and the upload contract

docs/openapi.yaml

@@ -96,10 +96,13 @@ paths:
       description: >
         multipart/form-data. The text fields (`workload`, `parameters`,
         `chunk_rows`, `max_rows`) MUST precede the `file` part: the file is streamed, not
-        buffered, so the fields have to be parsed before it arrives. Currently
+        buffered, so the fields have to be parsed before it arrives. The
-        only `similarity-search` with `parameters.query_smiles` is accepted.
+        workload must be an enabled, upload-ready entry of the embedded SDK
-        When every shard succeeds, the coordinator merges their candidates into
+        workload catalog, and `parameters` must satisfy its declared JSON
-        one final CSV; distributed graph planning is not implemented.
+        schema. When every shard succeeds, the coordinator reduces the partial
+        results (`top-k` workloads merge exactly; `ordered-concat` workloads
+        concatenate in shard order) into one final CSV; distributed graph
+        planning is not implemented.
       requestBody:
         required: true
         content:

mkdocs/index.md

@@ -32,7 +32,9 @@ The two halves of the project:
   tasks claimed from the coordinator, with digest-pinned `TaskSpec`s,
   resource reservation, and allowlist-driven workload discovery.
 - **An operator UI** served by the coordinator: the control room, a workload
-  library page, and this documentation site at `/ui/docs/`.
+  library page, a workload-agnostic "new computation" form whose controls come
+  from each workload's own `UIElement` declarations, and this documentation
+  site at `/ui/docs/`.
 
 ## Quick start
 

mkdocs/sdk/authoring-workloads.md

@@ -111,6 +111,39 @@ that keep the header, `shard_rows` rows each) and default `reduce_partials`
 | `resources` / `execution` | CPU-1 core defaults | Per-task resource and execution profile |
 | `shard_rows` | `1000` | Rows per shard for the default `partition_input` |
 | `map_entry_point` / `reduce_entry_point` | derived from the module | Handler keys (can stay default) |
+| `ui_elements` | `()` | `UIElement` declarations that shape the coordinator "new computation" form |
+| `reduction` | `"ordered-concat"` | Coordinator reduction mode: `ordered-concat` (row tables) or `top-k` |
+| `upload_ready` | `True` | Whether a single uploaded dataset can drive the workload (multi-input planners set `False`) |
+
+## Workload-declared UI elements
+
+The coordinator "new computation" page renders one form per workload from the
+embedded catalog. Workloads that need friendlier controls than plain schema
+fields declare them:
+
+```python
+from scimesh.sdk import UIElement
+
+ui_elements = (
+    UIElement(
+        "min_molwt", "number", "Minimum molecular weight",
+        help="Keep molecules with MolWt at least this value. Optional.",
+        placeholder="e.g. 100", order=1,
+    ),
+    UIElement(
+        "skip_invalid", "checkbox", "Skip invalid molecules",
+        help="Skip rows with invalid SMILES instead of failing the shard.",
+        default=True, order=3,
+    ),
+)
+```
+
+Each `field` must name a `parameters_schema` property. Widgets: `text`,
+`textarea`, `number`, `select` (requires `options`), and `checkbox`. When a
+workload declares no elements, the page falls back to schema-derived controls
+(defaults and descriptions from the schema still apply). The schema remains
+the authoritative contract: the coordinator re-validates submitted parameters
+against it server-side.
 
 ## Scientific hooks
 

mkdocs/sdk/worker-integration.md

@@ -62,9 +62,13 @@ register -> claim (one task) -> download input + verify sha256
 
 The task subprocess loads workloads from `SCIMESH_WORKLOAD_ALLOWLIST` (a
 JSON array of `{distribution, name, version, digest}` entries matched
-against installed `scimesh.workloads` entry points) or falls back to the
+against installed `scimesh.workloads` entry points) or falls back to every
-built-in `similarity-search`. Discovery measures the installed package
+enabled built-in SDK workload of the installed package — the same library
-before and after importing and fails transactionally on any mismatch.
+the coordinator embeds as its catalog. Discovery measures the installed
+package before and after importing and fails transactionally on any
+mismatch. The agent advertises the enabled catalog workloads as its
+capabilities unless `CAPABILITIES` is set explicitly. Generate an allowlist
+for a non-editable install with `scimesh workload allowlist`.
 
 ```bash
 make agent