diff --git a/17/umbraco-cms/.gitbook.yaml b/17/umbraco-cms/.gitbook.yaml
index 3ed40560275..0473609271e 100644
--- a/17/umbraco-cms/.gitbook.yaml
+++ b/17/umbraco-cms/.gitbook.yaml
@@ -154,4 +154,8 @@ redirects:
customizing/extending-overview/extension-types/modals/confirm-dialog: customizing/utilities/modals/confirm-dialog.md
customizing/searchable-trees: customizing/overview.md
customizing/section-trees: customizing/overview.md
+ customizing/extending-overview/extension-types/tree: customizing/extending-overview/extension-types/tree/README.md
+ customizing/extending-overview/extension-types/tree-item: customizing/extending-overview/extension-types/tree/README.md
+ customizing/extending-overview/extension-types/stores-and-repositories/tree-store: customizing/extending-overview/extension-types/tree/tree-repository.md
+ customizing/extending-overview/foundation/repositories/repository-types/tree-repository.md: customizing/extending-overview/extension-types/tree/tree-repository.md
diff --git a/17/umbraco-cms/SUMMARY.md b/17/umbraco-cms/SUMMARY.md
index 0743edc8530..c71b8ca26e6 100644
--- a/17/umbraco-cms/SUMMARY.md
+++ b/17/umbraco-cms/SUMMARY.md
@@ -188,7 +188,10 @@
* [Section](customizing/extending-overview/extension-types/sections/section.md)
* [Section Sidebar](customizing/extending-overview/extension-types/sections/section-sidebar.md)
* [Section View](customizing/extending-overview/extension-types/sections/section-view.md)
- * [Trees](customizing/extending-overview/extension-types/tree.md)
+ * [Trees](customizing/extending-overview/extension-types/tree/README.md)
+ * [Tree Repository](customizing/extending-overview/extension-types/tree/tree-repository.md)
+ * [Tree Models](customizing/extending-overview/extension-types/tree/tree-models.md)
+ * [Trees & Workspaces](customizing/extending-overview/extension-types/tree/trees-and-workspaces.md)
* [Workspaces](customizing/extending-overview/extension-types/workspaces/README.md)
* [Workspace Actions](customizing/extending-overview/extension-types/workspaces/workspace-editor-actions.md)
* [Workspace Action Menu Items](customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md)
@@ -219,7 +222,6 @@
* [Collection Repository](customizing/foundation/repositories/repository-types/collection-repository.md)
* [Detail Repository](customizing/foundation/repositories/repository-types/detail-repository.md)
* [Item Repository](customizing/foundation/repositories/repository-types/item-repository.md)
- * [Tree Repository](customizing/foundation/repositories/repository-types/tree-repository.md)
* [States](customizing/foundation/states.md)
* [Routes](customizing/foundation/routes.md)
* [Backoffice Localization](customizing/foundation/localization.md)
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/menu-item.md b/17/umbraco-cms/customizing/extending-overview/extension-types/menu-item.md
index a7a0598c407..ca09421f2b7 100644
--- a/17/umbraco-cms/customizing/extending-overview/extension-types/menu-item.md
+++ b/17/umbraco-cms/customizing/extending-overview/extension-types/menu-item.md
@@ -199,6 +199,27 @@ export const menuItemManifest: ManifestMenuItem = {
```
{% endcode %}
+#### Hiding the Tree Root
+
+To display tree items at the root level without a parent folder node, add `hideTreeRoot: true` to the menu item's meta:
+
+```typescript
+{
+ type: 'menuItem',
+ kind: 'tree',
+ alias: 'My.MenuItem.Tree',
+ meta: {
+ treeAlias: 'My.Tree',
+ menus: ['My.Menu'],
+ hideTreeRoot: true,
+ },
+}
+```
+
+{% hint style="info" %}
+The `hideTreeRoot` property must be set on the menuItem manifest, not the tree manifest.
+{% endhint %}
+
## Custom Menu Items
{% hint style="info" %}
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/stores-and-repositories/tree-store.md b/17/umbraco-cms/customizing/extending-overview/extension-types/stores-and-repositories/tree-store.md
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/tree-item.md b/17/umbraco-cms/customizing/extending-overview/extension-types/tree-item.md
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/tree.md b/17/umbraco-cms/customizing/extending-overview/extension-types/tree.md
deleted file mode 100644
index f4b813dc8b1..00000000000
--- a/17/umbraco-cms/customizing/extending-overview/extension-types/tree.md
+++ /dev/null
@@ -1,200 +0,0 @@
----
-description: A guide to creating a custom tree in Umbraco
----
-
-# Trees
-
-The tree is a hierarchical structure of nodes and is registered in the Backoffice extension registry. A tree can be rendered anywhere in the Backoffice with the help of the `` element.
-
-{% hint style="info" %}
-To see how to register a tree as a menu in a section, refer to the [Section Sidebar](./sections/section-sidebar.md) article.
-{% endhint %}
-
-## Creating trees
-
-To create a Tree in the Backoffice, you need to take multiple steps:
-
-### Registering a tree
-
-To register a tree, you need to create a manifest:
-
-```json
-{
- "type": "tree",
- "alias": "My.Tree.Alias",
- "name": "My Tree",
- "meta": {
- "repositoryAlias": "My.Repository.Alias"
- }
-}
-```
-
-### Rendering a tree
-
-To render a tree in the Backoffice, you can use the `` element. You need to provide the alias of the tree you want to render. The alias is the same as the one you registered in the manifest.
-
-```typescript
-
-```
-
-### Render a Custom Tree Item
-
-The `` element will render the tree items based on the registered tree item alias. The tree will be rendered using the [](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_tree.UmbDefaultTreeItemElement.html) element by default. If you want to render a custom tree item, you need to register a tree item manifest. This manifest can then show a custom element for the tree item.
-
-#### **The Tree Item Manifest**
-
-```json
-{
- "type": "treeItem",
- "alias": "Umb.TreeItem.Alias",
- "name": "My Tree Item",
- "element": "./my-tree-item.element.js",
- "conditions": {
- "entityType": "my-entity-type",
- },
-};
-```
-
-#### The Tree Item Element
-
-To create a custom tree item, you need to create a custom element. This element can optionally extend the [UmbTreeItemElementBase](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_tree.UmbTreeItemElementBase.html) class. However, it can also be used as a standalone element if you prefer to implement the tree item logic yourself.
-
-This example creates a custom tree item that extends the base class. The base class provides the necessary context and functionality for the tree item.
-
-```typescript
-import type { MyTreeItemDataModel } from './my-tree-item.model.js';
-import { UmbTreeItemElementBase } from '@umbraco-cms/backoffice/tree';
-import { html, nothing, customElement } from '@umbraco-cms/backoffice/external/lit';
-
-@customElement('my-tree-item')
-export class MyTreeItemElement extends UmbTreeItemElementBase {
- override render() {
- if (!this.item) return nothing;
- return html`
-
-
- ${this.item.name}
-
- `;
- }
-}
-
-export default MyTreeItemElement;
-```
-
-#### The Tree Item Model
-
-To define the data model for your tree item, you can create a model that extends the [UmbTreeItemModel](https://apidocs.umbraco.com/v16/ui-api/interfaces/packages_core_tree.UmbTreeItemModel.html). This model will be used to provide the data for your custom tree item.
-
-{% code title="my-tree-item.model.ts" %}
-```typescript
-import type { UmbTreeItemModel } from '@umbraco-cms/backoffice/tree';
-
-export interface MyTreeItemDataModel extends UmbTreeItemModel {
- // Add any additional properties you need for your tree item
-}
-```
-{% endcode %}
-
-
-### Adding data to the tree
-
-To add data to the tree, you need to create a repository that will provide the data for the tree. The repository is defined in the manifest of the tree and linked through its `repositoryAlias`.
-
-```json
-{
- "type": "repository",
- "alias": "My.Repository.Alias",
- "name": "My Repository",
- "api": "./my-repository.js"
-}
-```
-
-#### Implementing the repository
-
-The repository needs to be able to fetch data for the tree. You can implement the repository as a class that extends the [UmbTreeRepositoryBase](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_tree.UmbTreeRepositoryBase.html) class. This class provides the necessary methods to fetch data for the tree.
-
-{% code title="my-repository.ts" %}
-```typescript
-import { MyTreeDataSource } from './my-tree-data-source.js';
-import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
-import { UmbTreeRepositoryBase } from '@umbraco-cms/backoffice/tree';
-
-export class MyRepository extends UmbTreeRepositoryBase {
- constructor(host: UmbControllerHost) {
- super(host, MyTreeDataSource);
- }
-}
-```
-{% endcode %}
-
-#### Implementing the data source
-
-The data source is responsible for fetching the data for the tree. You can implement the data source as a class that implements the [UmbTreeDataSource](https://apidocs.umbraco.com/v16/ui-api/interfaces/packages_core_tree.UmbTreeDataSource.html) interface.
-
-{% code title="my-tree-data-source.ts" %}
-```typescript
-import type { MyTreeItemModel } from './my-tree-item.model.js';
-import type {
- UmbTreeAncestorsOfRequestArgs,
- UmbTreeChildrenOfRequestArgs,
- UmbTreeDataSource,
- UmbTreeRootItemsRequestArgs,
-} from '@umbraco-cms/backoffice/tree';
-
-export class MyTreeDataSource implements UmbTreeDataSource {
- async getRootItems(args: UmbTreeRootItemsRequestArgs) {
- // Fetch the root items for the tree
- return [
- {
- id: 'root1',
- name: 'Root Item 1',
- icon: 'icon-folder',
- },
- {
- id: 'root2',
- name: 'Root Item 2',
- icon: 'icon-folder',
- },
- ];
- }
-
- async getChildrenOf(args: UmbTreeChildrenOfRequestArgs) {
- // Fetch the children of the specified item
- if (args.id === 'root1') {
- return [
- {
- id: 'child1',
- name: 'Child Item 1',
- icon: 'icon-document',
- },
- {
- id: 'child2',
- name: 'Child Item 2',
- icon: 'icon-document',
- },
- ];
- }
- return [];
- }
-
- async getAncestorsOf(args: UmbTreeAncestorsOfRequestArgs) {
- // Fetch the ancestors of the specified item
- if (args.id === 'child1') {
- return [
- {
- id: 'root1',
- name: 'Root Item 1',
- icon: 'icon-folder',
- },
- ];
- }
- return [];
- }
-}
-```
-{% endcode %}
-
-## Further reading
-
-For more information on trees, you can refer to the examples folder in the GitHub repository: [Umbraco UI Examples - Trees](https://github.com/umbraco/Umbraco-CMS/tree/main/src/Umbraco.Web.UI.Client/examples/tree)
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/tree/README.md b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/README.md
new file mode 100644
index 00000000000..6e73353f6ec
--- /dev/null
+++ b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/README.md
@@ -0,0 +1,141 @@
+---
+description: A guide to creating a custom Tree in Umbraco
+---
+
+# Trees
+
+{% hint style="info" %}
+**New to sidebar navigation?** Read [Menus](../menu.md) and [Menu Items](../menu-item.md) first. For basic, static navigation you can use Menu Items alone. Trees are for **data-driven hierarchical structures** - use them when your Menu needs to display dynamic content from an API.
+{% endhint %}
+
+{% hint style="warning" %}
+To create a working Tree in the Backoffice, you need to understand three things:
+
+1. **[Populating Trees](#populating-trees)** - How to populate a Tree with data.
+2. **[Displaying Trees](#displaying-trees)** - How to display Trees and connect them to Menus to appear in the Section Sidebar or elsewhere.
+3. **[Trees and Workspaces](#trees-and-workspaces)** - How to navigate to Workspaces by clicking Menu Items.
+{% endhint %}
+
+## Populating Trees
+
+Trees get their data from a **Repository**. The Repository implements methods to return Tree Items and is referenced by the Tree Manifest via `repositoryAlias`.
+
+### Register the Repository
+
+```typescript
+{
+ type: 'repository',
+ alias: 'My.Tree.Repository',
+ name: 'My Tree Repository',
+ api: () => import('./my-tree.repository.js'),
+}
+```
+
+### Repository Implementation
+
+Create a Repository that implements the `TreeRepository` interface. The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_tree.UmbTreeRepository.html)
+
+```typescript
+interface UmbTreeRepository {
+ requestTreeRoot();
+ requestTreeRootItems();
+ requestTreeItemsOf();
+ requestTreeItemAncestors();
+}
+```
+
+For detailed implementation guidance, see:
+
+- **[Tree Repository](./tree-repository.md)** - Full repository implementation with static data example.
+- **[Tree Models](./tree-models.md)** - `UmbTreeItemModel` and `UmbTreeRootModel` interfaces.
+
+---
+
+## Displaying Trees
+
+### Tree Manifest
+
+Register your tree with a Manifest. The `repositoryAlias` links to how the Tree gets its data:
+
+```typescript
+{
+ type: 'tree',
+ kind: 'default',
+ alias: 'My.Tree',
+ name: 'My Tree',
+ meta: {
+ repositoryAlias: 'My.Tree.Repository',
+ },
+}
+```
+
+### Tree Item Manifest
+
+Tree-items define how individual items render. Use `kind: 'default'` for standard rendering:
+
+```typescript
+{
+ type: 'treeItem',
+ kind: 'default',
+ alias: 'My.TreeItem',
+ forEntityTypes: ['my-tree-root', 'my-tree-item'],
+}
+```
+
+{% hint style="info" %}
+Include both your root entity type and item entity type in `forEntityTypes` so the Tree Item renderer handles all nodes in your Tree.
+{% endhint %}
+
+### Standalone Rendering
+
+Trees can be rendered directly in custom components using the `` element:
+
+```html
+
+```
+
+### Connecting to a Menu
+
+Trees can also provide hierarchical data to **Menu Items**, which display the navigation you see in the Backoffice Section Sidebar.
+To register your Tree-based Menu Item use the `kind: 'tree'` in the Menu Item Manifest.
+
+```typescript
+{
+ type: 'menuItem',
+ kind: 'tree',
+ alias: 'My.MenuItem.Tree',
+ name: 'My Tree Menu Item',
+ weight: 100,
+ meta: {
+ label: 'My Tree',
+ icon: 'icon-folder',
+ entityType: 'my-tree-root',
+ menus: ['My.Menu'] // The Menu alias where this item should appear,
+ treeAlias: 'My.Tree',
+ hideTreeRoot: true, // Optional: show items at root level
+ },
+}
+```
+
+Examples of built-in Menus include:
+
+* Content - `Umb.Menu.Content`
+* Media - `Umb.Menu.Media`
+* Advanced Settings - `Umb.Menu.AdvancedSettings`
+
+See [Menu Items (Tree kind)](../menu-item.md#tree) and [Section Sidebar](../sections/section-sidebar.md) for the complete setup.
+
+---
+
+## Trees and Workspaces
+
+When users click a Tree Item, Umbraco navigates to a **Workspace** to edit that item. The `entityType` in your Tree Items must match the `meta.entityType` in your Workspace Manifest.
+
+See **[Trees & Workspaces](./trees-and-workspaces.md)** for setup details and troubleshooting.
+
+---
+
+## Further Reading
+
+- [Umbraco UI Examples - Trees](https://github.com/umbraco/Umbraco-CMS/tree/main/src/Umbraco.Web.UI.Client/examples/tree) - Working examples in the Umbraco repository.
+- [Workspaces](../workspaces/README.md) - Creating Workspace extensions.
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/tree/tree-models.md b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/tree-models.md
new file mode 100644
index 00000000000..42c135f69a3
--- /dev/null
+++ b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/tree-models.md
@@ -0,0 +1,101 @@
+---
+description: Understanding Tree Item and Root models in Umbraco
+---
+
+# Tree Models
+
+Trees use two model types to represent data: **Tree Item Model** for individual nodes and **Tree Root Model** for the root node. Your [Repository](./tree-repository.md) returns these models from its methods.
+
+## UmbTreeItemModel
+
+The base interface for Tree Items. All Tree Items must include these properties:
+
+```typescript
+interface UmbTreeItemModel {
+ unique: string; // Identifier for selection, navigation, and API calls
+ entityType: string; // Must match Workspace meta.entityType for navigation
+ name: string; // Display name shown in the tree
+ hasChildren: boolean; // Shows expand arrow when true
+ isFolder: boolean; // Visual styling hint
+ icon?: string; // Icon name (e.g., 'icon-document', 'icon-folder')
+ parent?: { // Parent reference for hierarchy and breadcrumbs
+ unique: string; // Parent's identifier
+ entityType: string; // Parent's entity type
+ };
+}
+```
+
+### Extending the Model
+
+Add custom properties by extending the base interface:
+
+```typescript
+import type { UmbTreeItemModel } from '@umbraco-cms/backoffice/tree';
+
+export interface MyTreeItemModel extends UmbTreeItemModel {
+ // Add custom properties
+ status: 'draft' | 'published';
+ lastModified: string;
+}
+```
+
+Your repository methods transform API responses into these models when returning data.
+
+## UmbTreeRootModel
+
+The root model represents the top-level node of your Tree. It extends `UmbTreeItemModel` but typically has `unique: null`:
+
+```typescript
+interface UmbTreeRootModel extends UmbTreeItemModel {
+ unique: null; // Root has no parent, so unique is null
+}
+```
+
+### Defining a Root Model
+
+```typescript
+import type { UmbTreeRootModel } from '@umbraco-cms/backoffice/tree';
+
+export interface MyTreeRootModel extends UmbTreeRootModel {
+ // Root-specific properties if needed
+}
+
+// Example root data returned by repository
+const rootData: MyTreeRootModel = {
+ unique: null,
+ entityType: 'my-tree-root',
+ name: 'My Tree',
+ hasChildren: true,
+ isFolder: true,
+ icon: 'icon-folder',
+};
+```
+
+The root model is returned by `requestTreeRoot()` in your [Tree Repository](./tree-repository.md).
+
+## Entity Types
+
+You typically define two entity types - one for the root and one for items:
+
+```typescript
+// types.ts
+export const MY_TREE_ROOT_ENTITY_TYPE = 'my-tree-root';
+export const MY_TREE_ITEM_ENTITY_TYPE = 'my-tree-item';
+
+export interface MyTreeRootModel extends UmbTreeRootModel {
+ entityType: typeof MY_TREE_ROOT_ENTITY_TYPE;
+}
+
+export interface MyTreeItemModel extends UmbTreeItemModel {
+ entityType: typeof MY_TREE_ITEM_ENTITY_TYPE;
+}
+```
+
+{% hint style="info" %}
+The `entityType` values must match the values in your Workspace and Tree Item Manifests. See [Trees & Workspaces](./trees-and-workspaces.md) for how these connect.
+{% endhint %}
+
+## Related
+
+- [Tree Repository](./tree-repository.md) - Returns Tree models from its methods.
+- [Trees & Workspaces](./trees-and-workspaces.md) - How `entityType` connects to Workspaces.
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/tree/tree-repository.md b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/tree-repository.md
new file mode 100644
index 00000000000..ca6b97e60fc
--- /dev/null
+++ b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/tree-repository.md
@@ -0,0 +1,111 @@
+# Tree Repository
+
+A Tree Repository provides data to populate your Tree. It implements methods to return the root, root items, children of items, and ancestors.
+
+The repository is referenced by your Tree Manifest via `meta.repositoryAlias`.
+
+## Interface
+
+The `UmbTreeRepository` interface defines the methods your repository must implement:
+
+```typescript
+interface UmbTreeRepository {
+ requestTreeRoot();
+ requestTreeRootItems();
+ requestTreeItemsOf();
+ requestTreeItemAncestors();
+}
+```
+
+See the full interface in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_tree.UmbTreeRepository.html).
+
+## Registering the Repository
+
+Register the Repository in your Manifest:
+
+```typescript
+{
+ type: 'repository',
+ alias: 'My.Tree.Repository',
+ name: 'My Tree Repository',
+ api: () => import('./my-tree.repository.js'),
+}
+```
+
+## Implementing a Tree Repository
+
+Extend `UmbControllerBase` and implement the `UmbTreeRepository` interface.
+
+### Static Data Example
+
+{% code title="static-tree.repository.ts" %}
+```typescript
+import { UmbControllerBase } from "@umbraco-cms/backoffice/class-api";
+import type { UmbApi } from "@umbraco-cms/backoffice/extension-api";
+import type { UmbTreeRepository } from "@umbraco-cms/backoffice/tree";
+
+const staticItems = [
+ {
+ unique: "1",
+ entityType: "my-item",
+ parent: { unique: null, entityType: "my-root" },
+ name: "First Item",
+ hasChildren: false,
+ isFolder: false,
+ icon: "icon-document",
+ },
+ {
+ unique: "2",
+ entityType: "my-item",
+ parent: { unique: null, entityType: "my-root" },
+ name: "Second Item",
+ hasChildren: false,
+ isFolder: false,
+ icon: "icon-document",
+ },
+];
+
+export class MyStaticTreeRepository
+ extends UmbControllerBase
+ implements UmbTreeRepository, UmbApi
+{
+ async requestTreeRoot() {
+ return {
+ data: {
+ unique: null,
+ entityType: "my-root",
+ name: "My Static Tree",
+ hasChildren: true,
+ isFolder: true,
+ icon: "icon-folder",
+ },
+ };
+ }
+
+ async requestTreeRootItems() {
+ const items = staticItems.filter((item) => item.parent.unique === null);
+ return { data: { items, total: items.length } };
+ }
+
+ async requestTreeItemsOf(args) {
+ const items = staticItems.filter(
+ (item) => item.parent.unique === args.parent.unique
+ );
+ return { data: { items, total: items.length } };
+ }
+
+ async requestTreeItemAncestors() {
+ // Implement as needed
+ return { data: [] };
+ }
+}
+
+export { MyStaticTreeRepository as api };
+```
+{% endcode %}
+
+## Related
+
+- [Tree Models](./tree-models.md) - `UmbTreeItemModel` and `UmbTreeRootModel` interfaces.
+- [Trees & Workspaces](./trees-and-workspaces.md) - How Tree clicks navigate to Workspaces.
+- [Trees](./README.md) - Main Tree extension documentation.
diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/tree/trees-and-workspaces.md b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/trees-and-workspaces.md
new file mode 100644
index 00000000000..febf8715dcb
--- /dev/null
+++ b/17/umbraco-cms/customizing/extending-overview/extension-types/tree/trees-and-workspaces.md
@@ -0,0 +1,55 @@
+---
+description: How Tree Items navigate to Workspaces when clicked in Umbraco
+---
+
+# Trees & Workspaces
+
+Trees and Workspaces are tightly coupled. When users click a Tree Item, Umbraco navigates to a Workspace to edit that item. This connection is established through the `entityType`, a string identifier that links Tree Items to their corresponding Workspace.
+
+## How Tree Items Connect to Workspaces
+
+When you click a Tree Item:
+
+1. Umbraco reads the `entityType` from the Tree Item data.
+2. It navigates to the edit Workspace URL, passing the items `unique` identifier.
+
+## Workspace Kind: Routable vs Default
+
+To support different routes for new and existing items, your Workspace must be routable to have different routes for each case. Use `kind: 'routable'` and set up matching routes in your Workspace API:
+
+```typescript
+// Tree Item Manifest
+{
+ type: 'treeItem',
+ kind: 'default',
+ alias: 'My.TreeItem',
+ forEntityTypes: ['my-custom-item'],
+}
+
+// Workspace Manifest - MUST be routable for Tree navigation
+{
+ type: 'workspace',
+ kind: 'routable',
+ alias: 'My.Workspace',
+ name: 'My Custom Item Workspace',
+ api: () => import('./my-custom-item-workspace.api.js'),
+ meta: {
+ entityType: 'my-custom-item', // Must match Tree Item entityType
+ },
+}
+```
+
+## Common Issues
+
+{% hint style="warning" %}
+**Endless loading when clicking Tree Items?** This usually means:
+
+- No Workspace is registered for that `entityType`.
+- The `entityType` in your Tree data doesn't match the Workspace's `meta.entityType`.
+-
+{% endhint %}
+
+## Related
+
+- [Trees](./README.md) - Main Tree extension documentation.
+- [Workspaces](../workspace/README.md) - Creating Workspace extensions.
diff --git a/17/umbraco-cms/customizing/foundation/repositories/repository-types/tree-repository.md b/17/umbraco-cms/customizing/foundation/repositories/repository-types/tree-repository.md
deleted file mode 100644
index 68f562ffd84..00000000000
--- a/17/umbraco-cms/customizing/foundation/repositories/repository-types/tree-repository.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Tree Repository
-
-A tree repository is a specific type of repository designed to handle operations related to tree data structures. It provides methods to request tree roots, tree items, and their ancestors.
-
-The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_tree.UmbTreeRepository.html).
-
-```typescript
-interface UmbTreeRepository {
- requestTreeRoot();
- requestTreeRootItems();
- requestTreeItemsOf();
- requestTreeItemAncestors();
-}
-```
\ No newline at end of file