doc: improve docs

Author: lhoupert

README.md

@@ -59,13 +59,7 @@ Make sure you have an `HARBOR_USERNAME` and `HARBOR_PASSWORD` for OVH container
 
 ### Setup port forwarding for webhook access
 
-To submit workflows via the HTTP webhook endpoint, set up port forwarding:
-
-```bash
-kubectl port-forward -n devseed-staging svc/eopf-explorer-webhook-eventsource-svc 12000:12000 &
-```
-
-This makes the webhook endpoint available at `http://localhost:12000/samples`.
+See [operator-tools/README.md](operator-tools/README.md#port-forwarding) for webhook port forwarding setup.
 
 ### For development
 
@@ -109,25 +103,13 @@ docker push w9mllyot.c1.de1.container-registry.ovh.net/eopf-sentinel-zarr-explor
 
 ## Submit Workflow
 
-### Method 1: HTTP Webhook (Production - Event-Driven)
-
-Submit STAC items via the HTTP webhook endpoint.
-
-**Using the interactive notebook (recommended):**
-
-```bash
-cd operator-tools
-jupyter notebook submit_stac_items_notebook.ipynb
-```
-
-**Using the Python script for single items:**
-
-```bash
-cd operator-tools
-python submit_test_workflow_wh.py
-```
+### Method 1: HTTP Webhook (Recommended)
 
-See [operator-tools/README.md](operator-tools/README.md) for detailed usage instructions.
+Use the operator tools to submit STAC items via HTTP webhook. See [operator-tools/README.md](operator-tools/README.md) for:
+- Interactive notebook for batch submissions
+- Python script for single item testing
+- Port forwarding setup
+- Common actions and target collections
 
 ### Method 2: kubectl (Testing - Direct Workflow Submission)
 
@@ -250,7 +232,7 @@ kubectl get wf -n devseed-staging --field-selector status.phase=Running
 | Problem | Solution |
 |---------|----------|
 | **"No group found in store"** | Using direct zarr URL instead of STAC item URL |
-| **"Webhook not responding"** | Verify port-forward is active: `ps aux \| grep "port-forward.*12000"` |
+| **"Webhook not responding"** | See [operator-tools troubleshooting](operator-tools/README.md#troubleshooting) |
 | **Workflow not starting** | Check webhook submission returned success, verify port-forward |
 | **S3 access denied** | Contact infrastructure team to verify S3 credentials |
 | **Workflow stuck/failed** | Check workflow logs: `kubectl logs -n devseed-staging -l workflows.argoproj.io/workflow=<name>` |

operator-tools/README.md

@@ -51,7 +51,7 @@ Submits a single test STAC item via HTTP webhook endpoint.
 **Usage:**
 
 ```bash
-python submit_test_workflow_wh.py
+uv run submit_test_workflow_wh.py
 ```
 
 **Configuration:**
@@ -60,7 +60,7 @@ Edit the script to change:
 
 - `source_url`: STAC item URL to process
 - `collection`: Target collection name
-- `action`: Processing action (e.g., `convert-v1-s2-hp`)
+- `action`: Processing action (e.g., `convert-v1-s2-hp`, or `convert-v1-s2-hp`)
 
 ### 2. `submit_stac_items_notebook.ipynb` - Interactive STAC Search & Submit
 
@@ -78,7 +78,7 @@ Jupyter notebook for searching and batch submitting STAC items.
 **Usage:**
 
 ```bash
-jupyter notebook submit_stac_items_notebook.ipynb
+uv run jupyter notebook submit_stac_items_notebook.ipynb
 ```
 
 **Features:**
@@ -98,22 +98,14 @@ Common target collections for processing:
 
 ## Payload Format
 
-All tools submit payloads in this format:
+All tools submit payloads with these fields:
 
-```json
-{
-  "source_url": "https://stac.core.eopf.eodc.eu/collections/sentinel-2-l2a/items/ITEM_ID",
-  "collection": "target-collection-name",
-  "action": "convert-v1-s2"
-}
-```
-
-**Fields:**
-
-- `source_url`: Full STAC item URL (self link)
+- `source_url`: Full STAC item URL (self link) - Must be a STAC API URL, not direct zarr
 - `collection`: Target collection for processed data
 - `action`: (Optional) Processing action/trigger to use
 
+See [main README payload examples](../README.md#payload-format) for correct/incorrect formats.
+
 ## Common Actions
 
 - `convert-v1-s2` - Standard Sentinel-2 conversion