---
name: eocube-stac-publish
description: "Use only when the user explicitly asks to publish, create or update STAC collections or items on stac.eocube.ro. Covers the ownership and visibility rules, collection naming, building items from local rasters, uploading assets and rewriting hrefs to permanent s3:// locations, validating, and adding or patching with the eocube MCP tools; deletion is CLI only after confirmation."
license: Apache-2.0
compatibility: "EOCube.RO JupyterHub notebooks (notebooks.eocube.ro) with the eocube MCP sidecar (eocube-tools 0.2.x) and the eocube CLI; writes require a logged-in platform account."
---

## Before writing anything

1. Call `auth_whoami`. The `username` it returns is the only value allowed in
   `eocube:owner` and the prefix of every collection id you create.
2. Decide the visibility. `eocube:visibility` is **an array** and must be set
   explicitly on every collection and item: `["public"]` for open data, `["private"]`
   for yourself only, or grants such as `["user:ro:<username>"]`,
   `["user:rw:<username>"]`, `["user:ro:*"]` (any authenticated user).
3. Non-admin collection ids must be `<username>-<id>` (for example
   `ion.popescu-flood-2026`). Items inherit the collection's access rules.

## Collections first

```text
collection = {
  "type": "Collection", "stac_version": "1.0.0",
  "id": "<username>-<id>", "description": "...", "license": "...",
  "extent": {"spatial": {"bbox": [[w, s, e, n]]}, "temporal": {"interval": [[start, end]]}},
  "links": [],
  "eocube:owner": "<username>", "eocube:visibility": ["private"]
}
```

`stac_validate_collection(collection=...)`, then `stac_create_collection(collection=...)`.
Update later with `stac_update_collection(collection_id, patch={...})`; never change
`eocube:owner`.

## Items from local rasters

1. `raster_discover_files(directory, recursive=True)` lists GDAL-readable files.
2. `raster_build_stac_item(paths=[...], item_id=..., item_datetime="2026-07-15T10:00:00Z",
   collection_id="<username>-<id>", compute_statistics=True, compute_file_info=True)`
   writes the item to a file and returns its path. All geospatial assets must share a CRS.
   The asset hrefs it produces are **relative local paths**.
3. Upload the files to EOCube storage, for example
   `eocube services storage upload local.tif <prefix>/local.tif --user` for the personal
   bucket, or `user_fs.put("local.tif", "<bucket>/<prefix>/local.tif")` from Python.
4. **Rewrite every asset href** in the item to its permanent location,
   `s3://<bucket>/<prefix>/local.tif` on the primary or personal endpoint. An item that
   still points at local paths is unreadable for everyone else.
5. Add `properties["eocube:owner"]` and `properties["eocube:visibility"]`.
6. `stac_validate_item(item_file=path)`; fix every reported issue.
7. `stac_add_item(collection_id, item_file=path)`.

Sentinel products on disk: `extract_sentinel2_l1c(granule_href, asset_href_prefix="s3://...")`
and `extract_sentinel1_slc(product_path)` build the item for you; step 3 onward still applies.

For items built by hand, prefer `pystac` or `rio-stac` over writing JSON: `proj:*`,
`eo:bands`, `datetime` and a bbox that agrees with the geometry are the usual mistakes.

## Updates

`stac_update_item(collection_id, item_id, patch={...})` merges a partial document. You may
update what you own or what grants you `user:rw:*`/`user:rw:<username>`. Preserve
`eocube:owner`.

## Deletion

The sidecar registers no delete tools. Deletion is destructive and irreversible for the
catalog entry: confirm the exact collection and item ids with the user first, then use
the CLI:

```bash
eocube services stac item delete <collection-id> <item-id>
eocube services stac collection delete <collection-id>
```

Assets in storage are not removed by a catalog delete.

## Checklist

- [ ] `eocube:owner` is the caller's username, on the collection and on every item.
- [ ] `eocube:visibility` is an array of valid tokens, set explicitly.
- [ ] Collection id is `<username>-<id>`.
- [ ] Every asset href is `s3://...` on an EOCube endpoint and the object exists.
- [ ] Validation passed before the write.
- [ ] The user confirmed any deletion.