amplience · Benj0s · Aug 20, 2025 · Jul 10, 2025 · Jul 11, 2025 · Jul 16, 2025
diff --git a/README.md b/README.md
@@ -207,5 +207,6 @@ In your Vercel project browse to Settings --> Environment Variables and edit the
 -   [Contribution Model (fork, PR, etc.)](https://github.com/amplience/dc-cli/blob/master/CONTRIBUTING.md)
 -   [FAQ](docs/FAQ.md)
 -   Upgrades:
+    -   [v5.0.0 Upgrade](docs/v5.0.0-upgrade.md)
     -   [v4.0.0 Upgrade](docs/v4.0.0-upgrade.md)
     -   [v3.0.0 Upgrade](docs/v3.0.0-upgrade.md)
diff --git a/docs/ArchDiagram.md b/docs/ArchDiagram.md
@@ -1,7 +1,7 @@
-
 # High-Level Architecture
 
-<!-- TODO: Update to look better -->
+## dc-demostore Architecture
+
 ![High-Level Architecture](../media/architecture.png)
 
-[back](../README.md)
+[back](../README.md)
diff --git a/docs/DeepDive.md b/docs/DeepDive.md
@@ -100,22 +100,24 @@ let filterRequest: GetByFilterRequest =
 
 ## Navigation Hierarchy
 
-![Site Pages](../media/sitePages.png)
+![alt text](../media/nav-sitePagesNew.png)
 
 The `Site Pages` hierarchy defines the top navigation of the site.
 This hierarchy is always loaded server-side and available for the Next.js pages.
 
-Each commerce related node (Site Pages and Category Page) has an option to populate sub nodes from commerce.
+Each commerce related node (Category Page and eComm Container) has an option to populate sub nodes from commerce. 
 
-![Site Pages](../media/site-pages-sub.png)
+The eComm Container allows you to select all commerce categories to be shown in the visualisation menu or a selection of your choice. These can be re-ordered as you wish. More than one eComm Container can be added to distribute the commerce categories through the visualisation menu as desired.
 
-When set to true, the navigation will auto populate sub items from the commerce category (or root).
+![alt text](../media/nav-ecommContainer.png)
 
-If set to false, only CMS managed sub items will appear.
+The Category Page allows you to select one commerce category. 
 
-CMS managed sub items will display AFTER the commerce items.
+![alt text](../media/nav-categoryPage.png)
 
-The default automation has the Site Pages node set to true to automatically render sub items from commerce.
+Further details are available at [WorkingWithPages.md](../docs/WorkingWithPages.md)
+
+The default automation has the eComm Container node set to Show All to automatically render all sub items from commerce.
 
 Other sub-hierarchies like `Components` and `Themes` are also always loaded in.
 

diff --git a/docs/ECommerceConfiguration.md b/docs/ECommerceConfiguration.md
@@ -19,7 +19,7 @@ For any of the supported integrations, you will need follow the guidance to setu
 
 Details can be found in [dc-demostore-integration](https://github.com/amplience/dc-integration-middleware) for each of the supported commerce vendors.
 
-## What do i need to change?
+## What do I need to change?
 
 There are 2 elements that you need to change to have your demostore work with a different supported eCommerce Vendor:
 

diff --git a/docs/FeatureHighlights.md b/docs/FeatureHighlights.md
@@ -3,6 +3,7 @@
 -   Content fully coming from Amplience Dynamic Content
 -   Multi-language & multi-currency front-end
 -   Multiple Components and Content Types implemented (banners, card lists, blogs, slots, etc.)
+-   Fully content managed 'Drag and Drop' hierarchy implementation.
 -   Multiple Visualisation implemented (page, standalone, time-based, etc.)
 -   Visualisation SDK implementation for Real-Time Visualisation from Amplience Dynamic Content
 -   Filter API implementation for Store page & Product Details Page personalisation

diff --git a/docs/WorkingWithPages.md b/docs/WorkingWithPages.md
@@ -4,35 +4,58 @@ The concepts of pages are a key demonstrable area of Demostore. They exist in 2
 
 ### Navigation:
 
--   **Category Page** - An item & page linked to a Commerce category (PLP)
--   **Landing Page** - An item and standalone page for content only
--   **External Page** - An item which has an external link for its page content
+-   **Landing Page** - A pure CMS driven page. An item and standalone page for content only. Via Page Group can link to a Category Page, External Page or another Landing Page. Shows as a CMS Item on hover in the visualisation.
+
+![alt text](../media/nav-landing-page.png)
+
+-   **Category Page** - Links directly to a commerce category and allows CMS content. An item & page linked to a Commerce category (PLP), to which Page Groups or further Category Pages can be added. Shows as a CMS Override Item on hover in the visualisation.
+
+![alt text](../media/nav-category-page.png)
+
+-   **Ecommerce Container** - Allows to you to draw all Ecommerce Categories into a single node - via Show All switch. Alternatively, select and reorder multiple Ecommerce Categories so you can control the order in which they appear in that existing node. Furthermore, you can use multiple Ecommerce Containers to distribute Ecommerce Categories amongst the CMS items. Shows as a Commerce Item on hover in the visualisation.
+
+![alt text](../media/nav-ecommerce-container.png)
+
+Show All above, below is selected Ecommerce Categories:
+
+![alt text](../media/nav-ecommerce-categories.png)
+
+-   **External Page** - Menu item that links to an external URL. As this links to an External site, there are no further items that can be added. Displays as CMS Item on hover in the visualisation.
+
+![alt text](../media/nav-external-page.png)
+
+-   **Page Group** - A grouping for sub nodes of any type with the exception of External Pages and Ecommerce Containers.
+
+![alt text](../media/nav-page-group.png)
 
 ### Standalone:
 
 -   **Content Page** - A page which can be used by itself without being in the menu.
 
 ## Ordering in Navigation
 
-Each item in the navigation has a `Priority` attribute. The number set in here is the order in which the navigation item is rendered.
+Each of the navigation items mentioned above can be arranged by dragging and dropping in the left-hand-side hierarchy menu. This provides a powerful and flexible way to arrange items in the menu according to preference.
+
+![alt text](../media/nav-ordering.png)
 
-Example: 0 will be first
+Existing drag-and-drop functionality, eg dragging a Page Group from a Landing Page to a Category Page continues to be available.
 
-The priority is in relation to other priorities set at the same at the same level in the hierarchy. So for example if you have 2 nodes at the same level
+When creating / adding an Ecommerce Container, you have two options:
 
--   MyItemA [Priority set to 50]
--   MyItemB [Priority set to 10]
+1. When the 'Show All' toggle switch is checked (default option), this will pull in all the Ecommerce Categories in the order they are obtained from the CMS.
 
-Will display as `MyItemB,MyItemA` in that order
+![alt text](../media/nav-show-all.png)
 
-> Note: When categories are set to automatically draw from commerce, they are given their priority with increments of 10 so that you can mix and max dynamic and curated navigation.
+2. When it is unchecked you will be able to manually select and arrange the eCommerce categories via drag-and-drop inside of the Ecommerce Container. In addition to the drag-and-drop re-ording function, here are a number of other functions available to enhance the user experience such as Move to top, Add below, Move to top etc
 
-> Additional node: If items have the same priority, they will display in order of which they are returned from the API.
+> Note: A Page Group can only be added as a child of a Category Page or Landing Page.
 
 ## Hiding a page
 
 Each of these content types has a flag in the content form called `is Active` which defaults to true.
 
+![alt text](../media/nav-is-active.png)
+
 If you disable this, then the page is no longer visible if attempting to visit it directly or in the menu navigation.
 
 ## Archiving a page & delivery keys

diff --git a/docs/v5.0.0-upgrade.md b/docs/v5.0.0-upgrade.md
@@ -0,0 +1,40 @@
+# V5.0.0 Upgrade
+
+## ⚠️ Breaking change v5.0.0 (after v4.3.0) ⚠️
+
+A breaking change was introduced _after_ version `v4.3.0` of this demostore FE due to depencies on the latest version of [dc-demostore-automation](https://github.com/amplience/dc-demostore-automation) `v5.0.0`
+
+In order for your demostore to function, you need the following:
+
+1. Automation should use latest automation `v5.0.0` from [dc-demostore-automation](https://github.com/amplience/dc-demostore-automation) using the lastest version of [dc-demostore-cli](https://github.com/amplience/dc-demostore-cli)
+2. Latest version of the dc-demostore-core FE from [dc-demostore-core](https://github.com/amplience/dc-demostore-core)
+
+### Recommended Upgrade path
+
+This path assumes that you already have an Amplience Dynamic Content account with content and a deployed URL in Vercel.
+
+1. Get latest version of dc-demostore-cli from npm
+
+`npm update @amplience/dc-demostore-cli` or if you installed globally `npm update @amplience/dc-demostore-cli -g`
+
+Once updated you can validate you are on the latest version by running the following command and checking that it matches the latest release on this github page:
+
+```
+demostore --version
+```
+
+2. Clean your Amplience Dynamic Content account to start from a blank canvas
+
+`demostore cleanup -c -a`
+
+3. Import from latest automation set
+
+`demostore import -l`
+
+See [import](../README.md#import) for details needed to update your front end
+
+4. Update your front end [dc-demostore-core](https://github.com/amplience/dc-demostore-core) to the latest version and deploy using the right environment variables
+
+### Staying on an older version
+
+Deployed versions will continue to work if you are not changing anything.
diff --git a/media/architecture.png b/media/architecture.png
diff --git a/media/nav-category-page.png b/media/nav-category-page.png
diff --git a/media/nav-categoryPage.png b/media/nav-categoryPage.png
diff --git a/media/nav-ecommContainer.png b/media/nav-ecommContainer.png
diff --git a/media/nav-ecommerce-categories.png b/media/nav-ecommerce-categories.png
diff --git a/media/nav-ecommerce-container.png b/media/nav-ecommerce-container.png
diff --git a/media/nav-external-page.png b/media/nav-external-page.png
diff --git a/media/nav-is-active.png b/media/nav-is-active.png
diff --git a/media/nav-landing-page.png b/media/nav-landing-page.png
diff --git a/media/nav-ordering.png b/media/nav-ordering.png
diff --git a/media/nav-page-group.png b/media/nav-page-group.png
diff --git a/media/nav-show-all.png b/media/nav-show-all.png
diff --git a/media/nav-sitePagesNew.png b/media/nav-sitePagesNew.png