update docs

Author: TejasMorbagal

docs/cli.md

@@ -28,3 +28,5 @@ Options:
 1. Reads your configs and builds dataset STAC collections plus variable catalogs.
 2. Builds workflow and experiment OGC API Records.
 3. Forks/clones the target metadata repo (production, staging, or testing), commits generated JSON, and opens a pull request on your behalf.
+
+The pull request description includes a "Generated with deep-code" attribution note.

docs/configuration.md

@@ -17,11 +17,12 @@ The sections below document every field in those templates.
 ```yaml
 # Required
 dataset_id: your-dataset.zarr
-collection_id: your-collection
+collection_id: your-collection       # no spaces — use hyphens
 license_type: CC-BY-4.0
+stac_catalog_s3_root: s3://bucket/stac/your-collection/
 
 # Optional
-osc_themes: [cryosphere]        # must match slugs at opensciencedata.esa.int/themes/catalog
+osc_themes: [cryosphere]        # must match slugs at opensciencedata.esa.int/themes/catalog — auto-lowercased
 osc_region: global
 dataset_status: completed       # ongoing | completed | planned (default: ongoing)
 documentation_link: https://example.com/docs
@@ -31,36 +32,27 @@ access_link: s3://bucket/your-dataset.zarr   # defaults to s3://deep-esdl-public
 cf_parameter:
   - name: sea_surface_temperature
     units: kelvin
-
-# Optional: publish a STAC Catalog + Item next to the data on S3.
-# When set, a lightweight STAC hierarchy (catalog.json → item.json) is written
-# directly to S3 and a "via" link is added to the OSC collection pointing to it.
-# S3 write credentials are resolved in order:
-#   1. STAC_S3_KEY / STAC_S3_SECRET  (STAC-specific, any bucket)
-#   2. AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
-#   3. boto3 default chain (IAM role, ~/.aws/credentials)
-stac_catalog_s3_root: s3://bucket/stac/your-collection/
 ```
 
 ### Field reference
 
 | Field | Required | Description |
 |---|---|---|
 | `dataset_id` | Yes | Zarr store identifier (used to open the dataset). |
-| `collection_id` | Yes | Unique ID for the STAC collection in the OSC catalog. |
-| `license_type` | Yes | SPDX license identifier (e.g. `CC-BY-4.0`). |
-| `osc_themes` | No | List of OSC theme slugs (e.g. `[cryosphere, oceans]`). |
+| `collection_id` | Yes | Unique ID for the STAC collection in the OSC catalog. **Must not contain spaces** — use hyphens as word separators (e.g. `My-Dataset-2024`). |
+| `license_type` | Yes | SPDX license identifier (e.g. `CC-BY-4.0`). Publishing fails if this field is absent. |
+| `osc_themes` | No | List of OSC theme slugs (e.g. `[cryosphere, oceans]`). Values are automatically lowercased so `Land` and `land` are equivalent. |
 | `osc_region` | No | Geographical region label (default: `Global`). |
 | `dataset_status` | No | One of `ongoing`, `completed`, or `planned` (default: `ongoing`). |
 | `access_link` | No | Public S3 URL of the Zarr store. Defaults to `s3://deep-esdl-public/{dataset_id}`. |
 | `documentation_link` | No | URL to dataset documentation. |
+| `visualisation_link` | No | URL to a visualisation of the dataset (e.g. xcube Viewer, WMS). Added as a `visualisation` link with title `"Dataset visualisation"`. |
 | `cf_parameter` | No | List of CF metadata dicts to override variable attributes (e.g. `name`, `units`). |
-| `stac_catalog_s3_root` | No | S3 root for the dataset-level STAC Catalog/Item. See [STAC Catalog on S3](#stac-catalog-on-s3). |
+| `stac_catalog_s3_root` | Yes | S3 root where the STAC Catalog and Item are published. Publishing fails if this field is absent. See [STAC Catalog on S3](#stac-catalog-on-s3). |
 
 ### STAC Catalog on S3
 
-Setting `stac_catalog_s3_root` generates a two-file STAC hierarchy on S3 alongside
-the data:
+`stac_catalog_s3_root` is required. deep-code writes a two-file STAC hierarchy to S3 alongside the data:
 
 ```
 s3://bucket/stac/your-collection/
@@ -124,7 +116,7 @@ links:
 | `properties.description` | No | Short summary of what the workflow does. |
 | `properties.keywords` | No | List of keyword strings. |
 | `properties.themes` | No | List of OSC theme slugs. |
-| `properties.license` | No | License identifier (e.g. `proprietary`, `CC-BY-4.0`). |
+| `properties.license` | Yes | SPDX license identifier (e.g. `CC-BY-4.0`, `proprietary`). Publishing fails if this field is absent. |
 | `jupyter_notebook_url` | No | Link to the source notebook on GitHub. When omitted, kernel and application links are skipped. |
 | `properties.jupyter_kernel_info` | No | Kernel name, Python version, and environment file URL. Only published when `jupyter_notebook_url` is set. |
 | `contact` | No | List of contact objects with `name`, `organization`, and `links`. |