docs: data-publishing user guide + configuration

docs/_config.yml

@@ -36,6 +36,9 @@ sphinx:
   local_extensions:
     azure_functions_simple: .
   config:
+    # Generate slug anchors for h1-h3 so in-page "[text](#heading)" links (the
+    # Contents lists) resolve as cross-references instead of warning.
+    myst_heading_anchors: 3
     autodoc_default_options:
       members: true
       undoc-members: true

docs/_toc.yml

@@ -7,6 +7,7 @@ parts:
       - file: usage/keyboard-shortcuts
       - file: usage/rapid-building-assessment
       - file: usage/damage-mapping
+      - file: usage/data-publishing
       - file: usage/building-blocks
         sections:
           - file: usage/projects

docs/configuration.md

@@ -19,6 +19,7 @@ This guide documents each configuration mode. For the end-to-end workflow, see
 - [Email sender domain](#email-sender-domain)
 - [Front Door](#front-door)
 - [Development mode](#development-mode)
+- [Data publishing](#data-publishing)
 - [First-admin bootstrap](#first-admin-bootstrap)
 - [Cleaning up an environment](#cleaning-up-an-environment)
 
@@ -296,6 +297,64 @@ The Docker Compose UI image pre-fills `administrators` in the SWA emulator's
 mock-login form. The source `staticwebapp.config.json` used for production is
 unchanged.
 
+## Data publishing
+
+Enables the **Published Datasets** feature and the **Publish** action on model results. The
+**Local** target (an immutable copy in the app's storage) is on by default; the **Planetary
+Computer** target is off until you configure it. For how the feature is used, see
+{doc}`Publishing datasets </usage/data-publishing>`.
+
+### Feature flags
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HASTE_PUBLISHING_ENABLED` | `true` | Master switch for the Published Datasets section and the Publish action. |
+| `HASTE_PC_PROVIDER_ENABLED` | `false` | Register/expose the Planetary Computer publishing target. |
+| `HASTE_PUBLISH_EXPLORER_RENDER_ENABLED` | `true` | Render a damage-classification COG and register the Explorer render/mosaic/tile config on Planetary Computer publish. |
+
+### Planetary Computer target
+
+Required to publish to a Microsoft Planetary Computer Pro GeoCatalog. The GeoCatalog is
+**external** to this template — you provision and own it (see the
+[out-of-app setup](usage/data-publishing.md#enabling-and-configuring-publishing)).
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HASTE_PC_GEOCATALOG_URL` | — | GeoCatalog base URL (no trailing slash). Required for the PC target. |
+| `HASTE_PC_EXPLORER_URL` | — | Explorer base URL used to build published-dataset links. |
+| `HASTE_PC_INGESTION_SOURCE` | — | GeoCatalog ingestion-source name. Only for **private** publish containers; public containers need none. |
+| `HASTE_PC_COLLECTION_PREFIX` | `haste-` | Prefix for STAC collection ids (one collection per project/event). |
+| `HASTE_PC_PUBLISHING_LICENSE` | `CC-BY-4.0` | STAC license id applied to published collections/items. |
+| `HASTE_PC_GEOCATALOG_INGEST_PRINCIPAL_ID` | — | Object id of the GeoCatalog managed identity to grant **Storage Blob Data Reader** on HASTE storage (asset ingestion). Empty = skip the role grant. |
+
+### Publish storage and attribution
+
+HASTE copies published assets into a network-reachable container the GeoCatalog ingests from,
+and records the operating organization as the STAC `processor` provider.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HASTE_PUBLISH_STORAGE_ACCOUNT_URL` | — | Storage account URL the GeoCatalog ingests published assets from. |
+| `HASTE_PUBLISH_BLOB_CONTAINER` | — | Blob container (on the publish storage account) HASTE copies published PC assets into. |
+
+```{admonition} The publish-store settings are an all-or-nothing pair
+:class: warning
+`HASTE_PUBLISH_STORAGE_ACCOUNT_URL` and `HASTE_PUBLISH_BLOB_CONTAINER` are used **only when
+both are set**. If either is empty, HASTE silently falls back to referencing assets **in
+place** from the primary artifact store — which a firewalled GeoCatalog cannot ingest, so
+publishing appears configured but fails at ingestion. Set both, or neither.
+```
+| `HASTE_PUBLISHING_ORGANIZATION_NAME` | — | Organization operating this deployment, recorded as the STAC `processor` provider. Empty = omit. |
+| `HASTE_PUBLISHING_ORGANIZATION_URL` | — | URL companion to `HASTE_PUBLISHING_ORGANIZATION_NAME`. |
+
+```{admonition} Organization attribution and PC URLs are treated as secrets in CI
+:class: note
+On the GitHub Actions deploy path the organization values and the GeoCatalog/publish-storage
+URLs are read from environment **secrets** (masked in logs), while the non-sensitive feature
+flags and collection prefix are environment **variables**. The Bicep/azd path reads them all
+as `HASTE_*` settings.
+```
+
 ## First-admin bootstrap
 
 Production uses `DEVELOPMENT_MODE=false`, so users are managed explicitly and are

docs/deployment.md

@@ -75,6 +75,23 @@ with per-job user-delegation SAS for tenant data isolation and capacity-aware
 routing. See [Shared multi-tenant GPU pools](configuration.md#shared-multi-tenant-gpu-pools)
 in the configuration guide.
 
+### Data publishing (optional)
+
+The **Local** publishing target works out of the box. Publishing to **Planetary Computer**
+depends on an **external** Microsoft Planetary Computer Pro GeoCatalog that you provision and
+own — it is not created by `azd up`. Before enabling the PC target, provision the GeoCatalog,
+give HASTE a publish storage container the GeoCatalog can ingest from, and set up the three
+role grants:
+
+- the HASTE Function App identity needs a **GeoCatalog data-plane RBAC role** on the
+  GeoCatalog resource (to call the STAC/ingestion APIs — this authorizes publishing itself);
+- the HASTE Function App identity needs **Storage Blob Data Contributor** on the publish store;
+- the GeoCatalog identity needs **Storage Blob Data Reader** on that store.
+
+The settings are documented under [Data publishing](configuration.md#data-publishing) in the
+configuration guide, and the end-to-end setup under
+[Publishing datasets](usage/data-publishing.md#enabling-and-configuring-publishing).
+
 ### Security
 
 For production deployments, follow the [Secure Configuration Guidance](security-configuration.md) — it covers identity and authentication setup, secrets management with managed identity and Key Vault, CORS and HTTP security headers, container hardening, logging and monitoring, and known limitations with operational mitigations. The guide also includes a pre-production checklist.

docs/usage/damage-mapping.md

@@ -152,6 +152,12 @@ reference.
 
 Each download shows its file size.
 
+### Publish the dataset
+
+If your administrator has enabled publishing, the Results menu also offers **Publish
+dataset…** — archive the result as a downloadable copy or share it to a Planetary Computer
+STAC catalog. See {doc}`Publishing datasets <data-publishing>`.
+
 ### Reports
 
 If you've validated buildings for this layer, the Results menu also offers a **Validation