@eeacms/volto-cca-policy 0.3.124 → 0.3.126

package/artifacts/link-integrity-workflow/link-integrity-block-fields-report.md

@@ -0,0 +1,132 @@
+# Link Integrity — Block Field Coverage Report
+
+**Date:** 2026-05-18
+**Scope:** All blocks registered by `volto-cca-policy`, analyzed against the link integrity retrievers available in `plone.restapi` and `eea.climateadapt`.
+
+---
+
+## Retrievers in Play
+
+Three retrievers scan block data when content is saved:
+
+| Retriever | Source | Order | Fields Scanned | Scope |
+|---|---|---|---|---|
+| `GenericBlockLinksRetriever` | `plone.restapi` | 1 | `url`, `href`, `preview_image` (top-level only) | All blocks (`block_type = None`) |
+| `TextBlockLinksRetriever` | `plone.restapi` | 100 | DraftJS `entityMap` LINK entities (`href`, `url`) | `block_type = "text"` |
+| `SlateBlockLinksRetriever` | `plone.restapi` | 100 | Slate nodes: `handle_a` → `data.link.internal.internal_link[0]["@id"]`, `handle_link` → `data.url` | `block_type = "slate"` |
+| `CCAObjectListLinksRetriever` | `eea.climateadapt` | 10 | `items[*].source`, `items[*].href`, `items[*].url`, top-level `linkTo`, top-level `image` | All blocks (`block_type = None`) |
+
+**Key constraint:** `GenericBlockLinksRetriever` only checks **top-level** fields named exactly `url`, `href`, or `preview_image`. It does NOT recurse into lists, dicts, or nested structures. Any link stored in a non-standard field name or nested inside a list requires the `CCAObjectListLinksRetriever` (or a new custom retriever).
+
+---
+
+## Block-by-Block Analysis
+
+### 1. Blocks WITH internal link fields — FULLY COVERED
+
+These blocks use standard top-level field names (`href`, `url`) that `GenericBlockLinksRetriever` catches, or their nested `items` are covered by `CCAObjectListLinksRetriever`.
+
+| Block | Field(s) | Widget | Covered By | Notes |
+|---|---|---|---|---|
+| **RedirectBlock** | `href` | `object_browser` | `GenericBlockLinksRetriever` | Standard `href` at top level |
+| **CountryMapObservatory** | `href` | `object_browser` | `GenericBlockLinksRetriever` | Standard `href` at top level |
+| **CollectionStatistics** | `href` | `object_browser` | `GenericBlockLinksRetriever` | Standard `href` at top level |
+| **ASTNavigation** | `href` (top-level) | `object_browser` | `GenericBlockLinksRetriever` | Main entry page link |
+| **ASTNavigation** | `items[*].href` | `object_browser` (in `object_list`) | `CCAObjectListLinksRetriever` | Nav items — `items` list with `href` field |
+| **ContentLinks** | `items[*].source` | `object_browser` (in `object_list`) | `CCAObjectListLinksRetriever` | `source` in items is explicitly handled |
+| **RelevantAceContent** | `items[*].source` | `object_browser` (in `object_list`) | `CCAObjectListLinksRetriever` | `source` in items is explicitly handled |
+
+### 2. Blocks WITH internal link fields — NOT COVERED (GAP)
+
+These blocks have fields that store internal links (via `object_browser`, path strings, or similar) but the field name or structure is **not** recognized by any existing retriever.
+
+| Block | Field(s) | Widget / Type | Why Not Covered | Risk |
+|---|---|---|---|---|
+| **Listing** (standard, extended) | `linkHref` | `object_browser` | Field name is `linkHref` — not in `GenericBlockLinksRetriever` (`url`, `href`, `preview_image`) and not in `CCAObjectListLinksRetriever` (`linkTo`, `image`). The CCA retriever checks `linkTo` but Volto core uses `linkHref`. | **Medium** — The "Link to..." / "More..." button link is silently missed. |
+| **RASTBlock** | `root_path` | plain `string` (path) | Stores a plain path string (e.g., `/en/knowledge-and-data/...`), NOT a `resolveuid/` URL. The retrievers only match strings containing `resolveuid`. | **Low** — Editors type paths manually; no object_browser. Moving the target folder breaks the link with no warning. |
+
+### 3. Blocks WITHOUT internal link fields — NO ACTION NEEDED
+
+These blocks either have no link-bearing fields, fetch content dynamically from the server, or use server-side `@components` views.
+
+| Block | Rationale |
+|---|---|
+| **C3SIndicatorsGlossaryBlock** | Empty schema. Content fetched from `@components` view `c3s_indicators_glossary_table`. |
+| **C3SIndicatorsListingBlock** | Empty schema. Content fetched from `@components` view `c3s_indicators_listing`. |
+| **C3SIndicatorsOverviewBlock** | Empty schema (category field commented out). Content fetched from `@components` view `c3s_indicators_overview`. |
+| **CaseStudyExplorer** | No schema file. Loads data from ArcGIS JSON endpoint (`@@case-studies-map.arcgis.json`). No content links stored in block data. |
+| **CountryMapHeatIndex** | No schema file. Renders country map from static GeoJSON + metadata endpoint. No content links in block data. |
+| **CountryMapProfile** | No schema file. Same pattern as CountryMapHeatIndex. No content links in block data. |
+| **CountryProfileDetail** | No schema file. Renders HTML from `@components` view `countryprofile`. |
+| **ECDEIndicators** | No schema file. Embeds CDS toolbox apps by region code. No content links in block data. |
+| **FilterAceContent** | Schema has only filter parameters (vocabularies, search text, sort). No `object_browser` or link fields. Results are fetched dynamically. |
+| **SearchAceContent** | Same as FilterAceContent — only filter/search parameters. No content links stored. |
+| **FlourishEmbedBlock** | `embed_code` is a `textarea` with raw HTML/JS. Not parsed by any retriever. Links (if any) are external Flourish URLs. |
+| **ReadMore** | Behavioral block only (labels, height, position). No links. |
+| **DataConnectedEmbedBlock** | Extends `@eeacms/volto-datablocks`. Only adds a `languageParam` string field. The base block's URL fields (if any) are handled by the base package's own mechanisms. |
+| **TransRegionSelect** | `region` is a vocabulary choice (not a link). Renders links dynamically from `@components` view. |
+| **TabsBlock (Spotlight)** | Container block. Links in child blocks are discovered recursively by `visit_blocks`. The spotlight variation's `image` field (in tab settings) is covered by `CCAObjectListLinksRetriever` (top-level `image`). |
+
+---
+
+## Summary of Gaps
+
+### Gap 1: Listing block — `linkHref` field
+
+**Problem:** The standard Volto listing block stores its "More..." link in a field named `linkHref`. The `GenericBlockLinksRetriever` only scans `url`, `href`, `preview_image`. The `CCAObjectListLinksRetriever` scans `linkTo` and `image` — neither matches `linkHref`.
+
+**Impact:** If an editor configures a listing block with a "Link to..." destination, and that destination is moved or made private, the link integrity system will NOT report this listing block as a breacher.
+
+**Remediation options:**
+1. **Extend `CCAObjectListLinksRetriever`** to also scan `linkHref` (add it to the top-level fields list alongside `linkTo` and `image`). This is the simplest fix — one line change.
+2. **Register a dedicated `ListingBlockLinksRetriever`** adapted to `block_type = "listing"`. More explicit but more code.
+
+**Recommendation:** Option 1 — add `linkHref` to the top-level fields in `CCAObjectListLinksRetriever`.
+
+### Gap 2: RASTBlock — `root_path` field
+
+**Problem:** `root_path` stores a plain content path (e.g., `/en/knowledge-and-data/rast`) as a string. It is NOT stored as `resolveuid/<UID>`, so even if the field name were recognized, `get_urls_from_value` would not match it (it checks for `resolveuid` in the string).
+
+**Impact:** If the root folder is moved, the RAST block silently points to a 404. No link integrity warning.
+
+**Remediation options:**
+1. **Change the widget** to `object_browser` and store as `resolveuid/` — then add `root_path` to a retriever. This is a schema change with migration implications.
+2. **Accept the risk** — the field is typed manually by editors and is inherently fragile regardless of link integrity.
+3. **Add a custom deserializer** that converts the path to `resolveuid/` on save, then add `root_path` to a retriever.
+
+**Recommendation:** Option 2 (accept risk) for now — the field is a single path string used by a small number of blocks, and converting it to `object_browser` would be a larger UX change. Document the limitation.
+
+---
+
+## Coverage Matrix
+
+| Block | Link Fields | Generic Retriever | CCA Retriever | Gap? |
+|---|---|---|---|---|
+| RedirectBlock | `href` | ✅ | — | No |
+| CountryMapObservatory | `href` | ✅ | — | No |
+| CollectionStatistics | `href` | ✅ | — | No |
+| ASTNavigation | `href` (top) | ✅ | — | No |
+| ASTNavigation | `items[*].href` | ❌ | ✅ | No |
+| ContentLinks | `items[*].source` | ❌ | ✅ | No |
+| RelevantAceContent | `items[*].source` | ❌ | ✅ | No |
+| **Listing** | `linkHref` | ❌ | ❌ | **Yes** |
+| RASTBlock | `root_path` | ❌ | ❌ | Yes (low risk) |
+| FlourishEmbedBlock | `embed_code` | ❌ | ❌ | N/A (external) |
+| All others | (none) | — | — | No |
+
+---
+
+## Notes on plone.restapi / plone.volto Checkouts
+
+- **plone.restapi** is checked out at `backend/sources/plone.restapi/`. It provides `GenericBlockLinksRetriever` (fields: `url`, `href`, `preview_image`), `TextBlockLinksRetriever` (DraftJS), and `SlateBlockLinksRetriever`.
+- **plone.volto** is NOT checked out in `backend/sources/`. It is installed as a packaged dependency in the backend venv. No custom link integrity retrievers were found in the EEA policy package (`eea.volto.policy`) — it only provides serialization/deserialization transformers, not link retrievers.
+- The `CCAObjectListLinksRetriever` in `eea.climateadapt` is the **only** custom link integrity retriever in the project. It runs at order 10 (before Generic at order 1, but both return independent lists that are unioned).
+
+---
+
+## Recommendations
+
+1. **Fix the Listing gap immediately** — add `linkHref` to `CCAObjectListLinksRetriever`'s top-level field scan (one-line change in `blocks_linkintegrity.py`).
+2. **Consider adding `image` to Generic coverage analysis** — `CCAObjectListLinksRetriever` already covers `image`, but if a future block uses `image` without items, it would only be caught by CCA's retriever.
+3. **Document the RASTBlock limitation** in the block's developer notes or BLOCKS.md.
+4. **Future blocks:** Always name link fields `href` or `url` at the top level, or `items[*].href` / `items[*].source` for nested lists, to benefit from existing retrievers.

package/artifacts/link-integrity-workflow/link-integrity-blocks-report.md

@@ -0,0 +1,52 @@
+# Volto Block Link Integrity Analysis Report - volto-cca-policy
+
+## Objective
+Identify blocks within the `volto-cca-policy` add-on that contain internal links in fields or structures not covered by the standard Plone/Volto link integrity discovery mechanisms.
+
+## Standard Coverage Recap
+
+The following mechanisms are provided by core packages:
+
+1.  **`plone.restapi` (Generic Retriever)**: Automatically extracts links from top-level fields: `url`, `href`, `preview_image`.
+2.  **`plone.restapi` (Visitors)**: Recursively visits sub-blocks stored in `blocks` or `data.blocks`.
+3.  **`plone.volto` (Visitors/Retrievers)**: Recursively visits sub-blocks stored in `columns`, `hrefList`, and `slides`.
+4.  **`eea.climateadapt` (Backend Custom Retriever)**: Specifically covers `items[*].source`, `items[*].href`, `items[*].url`, and top-level `linkTo` and `image`.
+
+## Analysis of volto-cca-policy Blocks
+
+| Block (@type) | Field Location | Covered? | Reason / Mechanism |
+| :--- | :--- | :--- | :--- |
+| `ContentLinks` | `items[*].source` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `RelevantAceContent` | `items[*].source` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `ASTNavigation` | `items[*].href` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `Listing` (Shadowed) | `linkTo` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `RedirectBlock` | `href` | **Yes** | `GenericBlockLinksRetriever` (Core) |
+| `CountryMapObservatory`| `href` | **Yes** | `GenericBlockLinksRetriever` (Core) |
+| `CollectionStatistics` | `href` | **Yes** | `GenericBlockLinksRetriever` (Core) |
+| `TabsBlock` (Spotlight)| `tabs[*].blocks` | **NO** | `tabs` key is not visited by core visitors. |
+| `TabsBlock` (Spotlight)| `tabs[*].image` | **NO** | `tabs` structure is not scanned for link fields. |
+| `FlourishEmbedBlock` | `embed_code` | **NO** | Raw HTML/JS (requires parsing). |
+| `CaseStudyExplorer` | `adaptation_options_links` | **NO** | Raw HTML (often dynamic source). |
+| `RASTBlock` | `root_path` | **NO** | Hardcoded string path (not a UID). |
+
+## Detailed Findings
+
+### 1. TabsBlock (Spotlight Variation)
+The `TabsBlock` in `volto-cca-policy` uses a custom `tabs` key to store a dictionary of tab data. Each tab can contain its own sub-blocks (`blocks` key) and a promotional `image`.
+*   **Sub-blocks Visibility**: Since neither `plone.restapi` nor `plone.volto` includes `tabs` in their `IBlockVisitor` implementations, the backend link integrity system is "blind" to any blocks placed inside a spotlight tab.
+*   **Image Visibility**: The `image` field within a tab is nested inside the `tabs` object list/map, which is not scanned by the generic or CCA-specific retrievers.
+
+### 2. FlourishEmbedBlock
+This block stores raw HTML or Javascript snippets for embedding Flourish charts. Internal links within these snippets are not tracked because they are not stored as structured data or `resolveuid/` patterns.
+
+### 3. RASTBlock
+Uses a `root_path` field which stores an absolute path as a string (e.g., `/en/knowledge-and-data/...`). Link integrity tracking depends on `resolveuid/` patterns and `zc.relation` objects. Paths are not automatically tracked or updated if the target moves.
+
+## Recommendations
+
+1.  **Expand Backend Retriever**: Update `CCAObjectListLinksRetriever` (or add a new one) to handle the `tabs` structure:
+    *   Visit each item in the `tabs` dictionary.
+    *   Extract links from the `image` field if present.
+    *   (Optional) If `tabs` items contain their own blocks, a custom `IBlockVisitor` should be registered to allow core recursion to reach them.
+2.  **Refactor RASTBlock**: If possible, change `root_path` to use a proper object browser widget and store a UID.
+3.  **Documentation**: Advise developers to stick to `blocks`, `columns`, or `slides` for sub-block storage, or `items` for list-based links to benefit from existing retrievers.

package/artifacts/link-integrity-workflow/understanding-link-integrity.md

@@ -0,0 +1,143 @@
+# Understanding Link Integrity in Plone and Volto
+
+## Use Case
+A user is editing a content item and decides to change its workflow state to "Private". Before this action is finalized, the system should check if other content items on the website are linking to this item. If such links exist, the user should be informed that these links will effectively "break" for public users (leading to an unauthorized screen).
+
+## Goal
+Identify a programmatic way (ideally a REST API endpoint) to retrieve a list of content items that link to a specific object.
+
+## Research Findings
+
+### 1. `plone.app.linkintegrity`
+- **Mechanism**: Tracks internal links using the `zc.relation` catalog with the relationship name `isReferencing`.
+- **Logic**: Extracts links from Dexterity `RichText` fields and Volto blocks (via `plone.volto`).
+- **Querying**: Provides utility functions in `plone.app.linkintegrity.utils`, notably `getIncomingLinks(obj)`.
+
+### 2. `plone.restapi`
+- **Existing Endpoints**:
+    - **`/@linkintegrity?uids=<UID>`**: Returns "breaches" (items linking to the specified UIDs). This is the same logic used by Plone's delete confirmation screen.
+    - **`/@relations?target=<UID>&relation=isReferencing`**: A more generic endpoint to query the relation catalog. Omitting the `relation` parameter returns all types of incoming relations (including `relatedItems`).
+- **Recommendation**: For the "warn before private" use case, `/@linkintegrity` is highly suitable because it returns structured data specifically designed for notifying users about broken links. However, `/@relations` is better if a simple list of *any* linking item is needed.
+
+### 3. `plone.volto` / Volto Frontend
+- **Backend**: Ensures that internal links within Volto blocks (columns, teasers, etc.) are correctly indexed by `plone.app.linkintegrity`.
+- **Frontend Logic**: 
+    - Volto has a `linkIntegrityCheck` action in `@plone/volto/actions` that calls the `/@linkintegrity` endpoint.
+    - The results are stored in the `linkIntegrity` reducer.
+    - The `ContentsDeleteModal` component in Volto core is the canonical example of how to display these breaches.
+- **Workflow Integration**: The state transition dropdown is managed by the `Workflow` component (`@plone/volto/components/manage/Workflow/Workflow`).
+
+## Recommended Solution
+
+To implement the "warn before private" feature:
+
+1. **Backend Endpoint**: Use `GET /@linkintegrity?uids=<UID>`.
+2. **Frontend Integration (Shadowing)**: 
+    - Shadow the core `Workflow` component by copying it to `frontend/src/addons/volto-cca-policy/src/customizations/volto/components/manage/Workflow/Workflow.jsx`.
+    - Intercept the `onChange` handler in the shadowed component.
+    - If the target state is "Private" (or similar), trigger the `linkIntegrityCheck`.
+    - Show a confirmation modal (similar to `ContentsDeleteModal`) if breaches are found.
+
+## Volto Implementation Details
+
+### Shadowing Path
+```
+frontend/src/addons/volto-cca-policy/src/customizations/volto/components/manage/Workflow/Workflow.jsx
+```
+
+### Logic Hook
+In the shadowed `Workflow.jsx`, modify the `transition` function:
+
+```javascript
+const transition = (selectedOption) => {
+  const isPrivateTransition = ['private', 'reject', 'retract'].includes(selectedOption.value) || 
+                               selectedOption.url.endsWith('/reject') || 
+                               selectedOption.url.endsWith('/retract');
+
+  if (isPrivateTransition) {
+    setPendingOption(selectedOption);
+    dispatch(linkIntegrityCheck([content.UID]));
+    setShowWarningModal(true);
+  } else {
+    executeTransition(selectedOption);
+  }
+};
+```
+
+### Components to reuse
+- `Confirm` from `semantic-ui-react` for the modal wrapper.
+*   **Existing Actions**: `linkIntegrityCheck` from `@plone/volto/actions`.
+*   **Existing Reducers**: `state.linkIntegrity.result` to access the breaches.
+*   **UI Reference**: `ContentsDeleteModal.jsx` in Volto core for the table rendering logic of broken links.
+
+## Final Implementation
+
+The feature was implemented in the `volto-cca-policy` add-on on a dedicated branch.
+
+### Git Branch
+- **Branch Name**: `link-integrity-workflow`
+
+### Files Created/Modified
+1.  **Shadowed Component**: `src/customizations/volto/components/manage/Workflow/Workflow.jsx`
+    - Shadowed from `@plone/volto/components/manage/Workflow/Workflow.jsx`.
+    - Modified to intercept state changes to `private`, `reject`, and `retract`.
+    - Integrated with `linkIntegrityCheck` action and `WorkflowLinkIntegrityModal`.
+2.  **New Component**: `src/components/manage/Workflow/WorkflowLinkIntegrityModal.jsx`
+    - A custom confirmation modal that displays link integrity breaches.
+    - Uses `semantic-ui-react` for the UI (Confirm, Table, Loader).
+    - Accesses `state.linkIntegrity.result` to render the list of affected content.
+3.  **Components Index**: `src/components/index.js`
+    - Exported `WorkflowLinkIntegrityModal` for use in the shadowed `Workflow` component.
+
+### Logic Summary
+- **Trigger**: When the user selects a "Private" transition in the workflow dropdown.
+- **Verification**: The `linkIntegrityCheck` action is dispatched for the current object's UID.
+- **Race Condition Prevention**: The system explicitly waits for the `linkIntegrity.loaded` state to be true before deciding whether to auto-proceed or show the modal. This prevents transitions from executing prematurely due to stale or initial empty state.
+- **Activity Indicators (UX)**: 
+    - During the link integrity check, a `Dimmer` and `Loader` are shown within the `WorkflowLinkIntegrityModal` with the message "Checking references...".
+    - During the actual workflow transition execution, a `Dimmer` and `Loader` are shown over the state selection dropdown to indicate that the transition is in progress.
+- **Interaction**:
+    - If no incoming links exist (`breaches.length === 0`), the transition proceeds automatically once the check is loaded.
+    - If incoming links are found, the `WorkflowLinkIntegrityModal` displays the list of referencing pages.
+    - The user can either "Cancel" the transition or select "Change state anyway" to proceed.
+
+## User Story: Testing the Link Integrity Warning
+
+### Description
+As a Content Editor, I want to be warned when I am about to make a page private if other pages are linking to it, so that I can avoid creating broken links for visitors.
+
+### Acceptance Criteria
+1.  **Positive Case (Breaches Found)**: 
+    - Given a "Target Page" that is published.
+    - Given a "Source Page" that contains a link to "Target Page".
+    - When I go to "Target Page" and select "Make Private" (or "Reject" / "Retract") from the state dropdown.
+    - Then I should see a "Checking references..." loading indicator.
+    - Then I should see a warning modal titled "Warning: Potential broken links".
+    - Then the modal should list "Source Page" as an item that will have a broken link.
+    - When I click "Cancel", the modal should close and the page should remain "Published".
+    - When I click "Change state anyway", the modal should close and the page should transition to "Private".
+
+2.  **Negative Case (No Breaches)**:
+    - Given a "Target Page" that is published and has NO incoming links.
+    - When I select "Make Private" from the state dropdown.
+    - Then I should see a brief "Checking references..." indicator.
+    - Then the page should transition to "Private" immediately without showing a warning modal.
+
+### Test Procedure
+1.  **Setup Content**:
+    - Create a page named "Linked Page" and Publish it.
+    - Create another page named "Referencing Page". 
+    - In "Referencing Page", add a Text block and insert an internal link to "Linked Page". Publish "Referencing Page".
+2.  **Verify Warning**:
+    - Navigate to "Linked Page".
+    - Open the state dropdown in the toolbar.
+    - Select "Make Private".
+    - **Observe**: The "Checking references..." dimmer should appear briefly.
+    - **Verify**: The warning modal should appear listing "Referencing Page".
+3.  **Test Cancellation**:
+    - Click "Cancel" in the modal.
+    - **Verify**: The page is still in "Published" state.
+4.  **Test Confirmation**:
+    - Select "Make Private" again.
+    - Click "Change state anyway" in the modal.
+    - **Verify**: The page state changes to "Private" and a success toast appears.

package/artifacts/link-integrity-workflow/volto-block-link-analysis.md

@@ -0,0 +1,63 @@
+# Volto Block Link Discovery Analysis - volto-cca-policy
+
+This document analyzes the custom blocks defined in the `volto-cca-policy` add-on to identify which fields contain internal links and whether they are covered by the standard Plone/Volto link integrity discovery mechanism.
+
+## Standard Discovery Mechanism Recap
+
+As documented in `volto-block-link-discovery.md`, the `GenericBlockLinksRetriever` automatically extracts internal links from the following top-level fields:
+- `url`
+- `href`
+- `preview_image`
+
+Any field not named exactly like one of these, or any link nested within a list or dictionary (unless it's a `blocks` container), requires a specialized retriever on the backend.
+
+## Analysis of volto-cca-policy Blocks
+
+### 1. Blocks Covered by Generic Retriever
+The following blocks use standard field names at the top level and should be automatically tracked.
+
+| Block | Field | Description |
+|---|---|---|
+| `RedirectBlock` | `href` | The target object for the redirection. |
+| `CountryMapObservatory` | `href` | The parent location of all country profiles. |
+| `CollectionStatistics` | `href` | The destination listing page. |
+| `ASTNavigation` | `href` | The main entry page to AST/UAST (top-level). |
+
+### 2. Blocks NOT Covered (Custom Field Names)
+The following blocks use field names that are not recognized by the generic retriever.
+
+| Block | Field | Description |
+|---|---|---|
+| `Listing` (Shadowed) | `linkTo` | Standard Volto listing block uses `linkTo` for the "More..." link. |
+
+### 3. Blocks NOT Covered (Nested Links)
+The following blocks store links within an `object_list`. The generic retriever does not scan inside these lists.
+
+| Block | Field Path | Description |
+|---|---|---|
+| `ContentLinks` | `items[*].source` | A list of hand-picked content items. |
+| `RelevantAceContent` | `items[*].source` | A list of hand-picked content items (assigned items). |
+| `ASTNavigation` | `items[*].href` | Individual navigation steps in the AST map. |
+
+### 4. Special Cases
+
+#### `FlourishEmbedBlock`
+- **Field**: `embed_code` (Textarea)
+- **Status**: Not covered.
+- **Reason**: Contains raw HTML/JS snippets. Discovery would require parsing the HTML for URLs, which is not performed by the standard block retrievers.
+
+#### `TabsBlock` (Spotlight Variation)
+- **Status**: Covered (indirectly).
+- **Reason**: This is a container block. The `NestedBlocksVisitor` handles the recursion into its child blocks, so any links within those children will be discovered normally.
+
+#### `ReadMore`
+- **Status**: No Links.
+- **Reason**: This is a behavioral block that manipulates the DOM of its siblings on the frontend. It does not store links in its own block data.
+
+## Recommendations for Link Integrity
+
+To ensure full coverage for `volto-cca-policy` content, the following actions are recommended:
+
+1.  **Backend Adapters**: Register custom `IBlockFieldLinkIntegrityRetriever` adapters for `ContentLinks`, `RelevantAceContent`, and `ASTNavigation` to extract links from their `items` lists.
+2.  **Field Mapping**: If possible, refactor `ContentLinks` and `RelevantAceContent` to use `href` or `url` instead of `source` for individual items, although a custom retriever is still needed for the list structure.
+3.  **Core Coverage**: Verify if `plone.restapi` or `plone.volto` provides a specialized retriever for the `listing` block's `linkTo` field. If not, one should be added.

package/artifacts/link-integrity-workflow/volto-block-link-discovery.md

@@ -0,0 +1,60 @@
+# How Volto Discovers Links in Blocks for Link Integrity
+
+When a content item is saved in Plone, the system needs to know which other internal items it links to, so it can maintain the `zc.relation` catalog (specifically using the `isReferencing` relationship). 
+
+For traditional Plone, this meant parsing HTML in `RichText` fields. For Volto, the content is stored as JSON blocks, requiring a recursive discovery mechanism.
+
+## Sub-block Storage and Discovery
+
+Sub-blocks are stored in the JSON data of a parent block using one of two primary patterns. The Plone backend uses a recursive generator called `visit_blocks` (defined in `plone.restapi.blocks`) to walk this tree.
+
+### 1. Dictionary Mapping (Key-Value)
+This is the standard Volto pattern for container-like blocks.
+- **Storage Pattern**: A dictionary where keys are UUIDs and values are the sub-block data.
+- **Common Keys**: `blocks` or `data["blocks"]`.
+- **Discovery**: `plone.restapi.blocks.NestedBlocksVisitor` is registered for these keys. It yields each value in the dictionary.
+
+### 2. Sequential Lists
+This pattern is used by layout-oriented blocks where the order is strictly positional.
+- **Storage Pattern**: A simple list of block data objects.
+- **Core Volto Keys**: `columns`, `slides`, `hrefList`.
+- **Discovery**: `plone.volto.transforms.NestedBlocksVisitor` handles these keys. It iterates through the list and yields each block.
+
+### 3. Recursive Discovery Logic
+The `visit_blocks` function uses `IBlockVisitor` subscribers to find children. When a visitor yields a sub-block, `visit_blocks` immediately recurses into that sub-block. This ensures that a block tree of any depth (e.g., a Grid containing Columns containing Teasers) is fully flattened during the discovery phase.
+
+## Internal Link Extraction
+
+Once a block is discovered, the `BlocksRetriever` (in `plone.restapi.blocks_linkintegrity`) uses `IBlockFieldLinkIntegrityRetriever` subscribers to find internal links within that specific block's fields.
+
+### Automatic Link Detection (The Generic Retriever)
+The `GenericBlockLinksRetriever` provides a "zero-configuration" discovery for most custom blocks. It automatically scans the following fields if they contain the `resolveuid/` pattern:
+- `url`
+- `href`
+- `preview_image`
+
+**Note**: If a block uses custom field names for links (e.g., `source`, `target`, `link_to`), they will **NOT** be caught by the generic retriever unless they are specifically registered.
+
+### Complex Data Extraction
+Some blocks store links deep within complex JSON structures rather than simple top-level strings. These require specialized retrievers:
+
+1. **Slate Blocks (Rich Text)**:
+   - Uses `SlateBlockLinksRetriever`.
+   - Recursively walks the Slate node tree.
+   - Extracts UIDs from `data.link.internal.internal_link[0]["@id"]` and `data.url`.
+
+2. **DraftJS Blocks (Legacy Text)**:
+   - Uses `TextBlockLinksRetriever`.
+   - Parses the `entityMap` for `LINK` entities.
+   - Extracts data from `url` and `href` keys within the entity data.
+
+## Redundancy and Reliability
+To ensure maximum reliability, `plone.volto` includes a `NestedBlockLinkRetriever` (registered with `block_type = None`). This serves as a fail-safe that manually walks the `columns`, `hrefList`, and `slides` keys to trigger link extraction, providing a second layer of defense for nested layouts.
+
+## Summary for Developers
+To ensure a custom block is correctly tracked by the link integrity system:
+
+1.  **Field Naming**: Prefer naming your link fields `url` or `href` to benefit from the generic retriever.
+2.  **Nesting**: If your block contains sub-blocks, store them in a dictionary under the key `blocks`.
+3.  **Link Format**: Always store internal links using the `resolveuid/<UID>` format.
+4.  **Custom Retrievers**: If you must use unique field names or storage patterns, register a custom `IBlockFieldLinkIntegrityRetriever` adapter for your block's `@type` in the backend.